{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/api.brenvio.com.br" } ], "info": { "name": "Br Envio API v1 (p\u00fablica)", "_postman_id": "7d6f1bbc-46dc-450b-b34c-0c48fb5c3e40", "description": "API p\u00fablica de integra\u00e7\u00e3o do Br Envio: contatos, tags, envio avulso e webhooks. Leia o Getting Started no portal.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Integra\u00e7\u00e3o de Contatos", "description": "\nSincronize contatos a partir do seu CRM, loja ou ERP.\n\n**Autentica\u00e7\u00e3o:** `Authorization: Bearer ` (token em Integra\u00e7\u00f5es \u2192 Tokens de API).\n**Limite:** 60 requisi\u00e7\u00f5es\/minuto por token.\n**Resposta:** envelope `{ success, data }` ou `{ success: false, error }`.\n\nA chave de identidade \u00e9 sempre o **e-mail** (min\u00fasculas). Tags e campos tipados\ns\u00e3o opcionais. Contatos descadastrados ou suprimidos **n\u00e3o** s\u00e3o reativados por esta rota.", "item": [ { "name": "Criar ou atualizar contato (upsert)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/integration\/contacts", "query": [], "raw": "{{baseUrl}}\/api\/v1\/integration\/contacts" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"email\":\"helena@crm.test\",\"name\":\"Helena\",\"country_code\":\"55\",\"phone_number\":\"11988887777\",\"phone\":\"+55 11 98888-7777\",\"tags\":[\"Lead CRM\",\"VIP\"],\"tag_match\":\"append\",\"fields\":{\"empresa\":\"Acme\"}}" }, "description": "Cria o contato se o e-mail for novo; atualiza se j\u00e1 existir na conta.\n\n**Tags:** envie nomes em `tags`. Nomes inexistentes s\u00e3o criados automaticamente.\nCom `tag_match=append` (padr\u00e3o) as tags s\u00e3o **anexadas**. Com `replace`, o array\nenviado vira o conjunto completo (\u00fatil quando o CRM \u00e9 a fonte da verdade).\n\n**Campos tipados (`fields`):** objeto `{ \"slug\": valor }` com slugs cadastrados em\nAudi\u00eancia \u2192 Campos da base. S\u00f3 os slugs enviados mudam (upsert parcial).\nSlug desconhecido \u2192 `UNKNOWN_FIELD_SLUG`.\n\n**Telefone:** preferir `country_code` + `phone_number` (s\u00f3 d\u00edgitos). Alternativa:\nstring `phone` (o servidor normaliza; DDI padr\u00e3o `55` se faltar).\n\n**Higiene:** lista de bloqueio \u2192 `CONTACT_BLOCKLISTED`; supress\u00e3o global \u2192\n`CONTACT_SUPPRESSED`. Contatos `unsubscribed` \/ `suppressed` n\u00e3o s\u00e3o reativados.\n\nHTTP **201** + `data.created=true` (criado) ou **200** + `created=false` (atualizado)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"message\": \"Contato atualizado via integra\u00e7\u00e3o.\",\n \"data\": {\"id\": 1, \"email\": \"helena@crm.test\", \"created\": false}\n}", "name": "atualizado" }, { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"message\": \"Contato criado via integra\u00e7\u00e3o.\",\n \"data\": {\n \"id\": 1,\n \"email\": \"helena@crm.test\",\n \"name\": \"Helena\",\n \"status\": \"active\",\n \"tags\": [{\"id\": 1, \"name\": \"VIP\"}],\n \"fields\": {\"empresa\": \"Acme\"},\n \"created\": true\n }\n}", "name": "criado" }, { "header": [], "code": 401, "body": "{\n \"success\": false,\n \"error\": {\"code\": \"UNAUTHORIZED\", \"message\": \"Autentica\u00e7\u00e3o necess\u00e1ria.\"}\n}", "name": "sem_token" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"error\": {\"code\": \"CONTACT_BLOCKLISTED\", \"message\": \"Este e-mail ou dom\u00ednio est\u00e1 na lista de bloqueio e n\u00e3o pode ser cadastrado.\"}\n}", "name": "lista_bloqueio" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"error\": {\"code\": \"CONTACT_SUPPRESSED\", \"message\": \"Este e-mail ou dom\u00ednio est\u00e1 na lista de supress\u00e3o e n\u00e3o pode ser cadastrado.\"}\n}", "name": "supressao" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"error\": {\"code\": \"UNKNOWN_FIELD_SLUG\", \"message\": \"Slug de campo desconhecido.\"}\n}", "name": "campo_desconhecido" }, { "header": [], "code": 429, "body": "{\n \"success\": false,\n \"error\": {\"code\": \"RATE_LIMIT_EXCEEDED\", \"message\": \"Limite de requisi\u00e7\u00f5es excedido. Tente novamente em instantes.\"}\n}", "name": "rate_limit" } ] } ] }, { "name": "Tags", "description": "\nCat\u00e1logo de marcadores (tags) da conta \u2014 r\u00f3tulos como \"VIP\", \"Lead CRM\", \"Carrinho\".\n\n**Neste portal** use apenas as rotas `\/api\/v1\/integration\/tags*` com\n`Authorization: Bearer `. Limite: 60 req\/min. Envelope `{ success, data }`.\n\nPara **vincular** tags a um contato, use o upsert de contatos (`tags` + `tag_match`),\nn\u00e3o estas rotas de cat\u00e1logo.", "item": [ { "name": "Listar tags", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/integration\/tags", "query": [ { "key": "search", "value": "vip", "description": "Filtro parcial no nome (sem diferenciar mai\u00fasculas).", "disabled": false }, { "key": "per_page", "value": "15", "description": "Itens por p\u00e1gina (1\u2013100, padr\u00e3o 15).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/integration\/tags?search=vip&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna a lista paginada do cat\u00e1logo. Use `search` para filtrar por nome\n(busca parcial, sem diferenciar mai\u00fasculas\/min\u00fasculas) e `per_page` (1\u2013100, padr\u00e3o 15)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [{\"id\": 1, \"name\": \"VIP\", \"contacts_count\": 12}],\n \"meta\": {\"current_page\": 1, \"per_page\": 15, \"total\": 1, \"last_page\": 1}\n}", "name": "ok" } ] }, { "name": "Criar tag", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/integration\/tags", "query": [], "raw": "{{baseUrl}}\/api\/v1\/integration\/tags" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Lead CRM\"}" }, "description": "Cria um marcador pelo nome. Nome j\u00e1 existente (sem diferenciar mai\u00fasculas) \u2192 valida\u00e7\u00e3o 422." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"message\": \"Tag criada.\",\n \"data\": {\"id\": 1, \"name\": \"Lead CRM\"}\n}", "name": "criada" } ] }, { "name": "Detalhe da tag", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/integration\/tags\/:tag", "query": [], "raw": "{{baseUrl}}\/api\/v1\/integration\/tags\/:tag", "variable": [ { "id": "tag", "key": "tag", "value": 1, "description": "ID da tag." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna id e nome. ID inexistente ou de outra conta \u2192 404 (`NOT_FOUND`)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\"id\": 1, \"name\": \"VIP\"}\n}", "name": "ok" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"error\": {\"code\": \"NOT_FOUND\", \"message\": \"Recurso n\u00e3o encontrado.\"}\n}", "name": "nao_encontrada" } ] }, { "name": "Renomear tag", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/integration\/tags\/:tag", "query": [], "raw": "{{baseUrl}}\/api\/v1\/integration\/tags\/:tag", "variable": [ { "id": "tag", "key": "tag", "value": 1, "description": "ID da tag." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"VIP 2026\"}" }, "description": "Altera apenas o nome. Os v\u00ednculos com contatos permanecem (s\u00f3 o r\u00f3tulo muda)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"message\": \"Tag atualizada.\",\n \"data\": {\"id\": 1, \"name\": \"VIP 2026\"}\n}", "name": "ok" } ] }, { "name": "Excluir tag", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/integration\/tags\/:tag", "query": [], "raw": "{{baseUrl}}\/api\/v1\/integration\/tags\/:tag", "variable": [ { "id": "tag", "key": "tag", "value": 1, "description": "ID da tag." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Remove a tag e os v\u00ednculos com contatos. Os **contatos** em si n\u00e3o s\u00e3o apagados." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"message\": \"Tag exclu\u00edda.\",\n \"data\": null\n}", "name": "ok" } ] } ] }, { "name": "Envio Avulso", "description": "\nEnvie **um** e-mail por requisi\u00e7\u00e3o (recibo, senha, aviso 1:1) \u2014 sem disparar campanha em massa.\n\n**Autentica\u00e7\u00e3o:** `Authorization: Bearer `.\n**Limite:** 60 req\/min. **Cota:** cada aceite (HTTP 202) consome **1** e-mail do plano.\n**Ass\u00edncrono:** 202 significa \u201centrou na fila\u201d; o envio real ocorre em background.\n\nPr\u00e9-requisitos da conta: setup de dom\u00ednio\/remetente completo; cota dispon\u00edvel;\nconta sem bloqueio de sa\u00fade (circuito\/congelamento).", "item": [ { "name": "Enviar mensagem", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/messages", "query": [], "raw": "{{baseUrl}}\/api\/v1\/messages" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"to_email\":\"cliente@empresa.test\",\"subject\":\"Seu pedido #123\",\"html_body\":\"

Ol\u00e1, seu pedido saiu!<\\\/p>\",\"text_body\":\"Ol\u00e1, seu pedido saiu!\",\"message_type\":\"transactional\",\"from_email\":\"ola@acme.test\",\"from_name\":\"Acme\"}" }, "description": "Aceita o envio depois de validar: setup de dom\u00ednio, sa\u00fade da conta, higiene\n(lista de bloqueio \/ supress\u00e3o), descadastro (s\u00f3 se `message_type=marketing`),\ncota do plano e capacidade da fila priorit\u00e1ria.\n\nResposta **202**: `data.status` come\u00e7a como `pending`. Consulte\n`GET \/api\/v1\/messages\/{id}` ou assine webhooks `message.sent` \/ `message.failed`\n(ver Getting Started \u2192 Receita C).\n\nInforme `html_body` **ou** `text_body` (pelo menos um).\n\n| `message_type` | Quando usar | Descadastro de marketing |\n|----------------|-------------|---------------------------|\n| `transactional` | Recibo, senha, NF, aviso operacional | N\u00e3o aplica; ainda respeita blocklist\/supress\u00e3o |\n| `marketing` | Promo\u00e7\u00e3o \/ newsletter 1:1 | Respeita descadastro |" }, "response": [ { "header": [], "code": 202, "body": "{\n \"success\": true,\n \"message\": \"Mensagem enfileirada. O envio come\u00e7a em instantes.\",\n \"data\": {\"id\": 1, \"status\": \"pending\"}\n}", "name": "aceito" }, { "header": [], "code": 401, "body": "{\n \"success\": false,\n \"error\": {\"code\": \"UNAUTHORIZED\", \"message\": \"Autentica\u00e7\u00e3o necess\u00e1ria.\"}\n}", "name": "sem_token" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"error\": {\"code\": \"QUOTA_EXCEEDED\", \"message\": \"A cota de e-mails do ciclo acabou.\"}\n}", "name": "cota" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"error\": {\"code\": \"CONTACT_SUPPRESSED\", \"message\": \"Este e-mail ou dom\u00ednio est\u00e1 na lista de supress\u00e3o e n\u00e3o pode ser cadastrado.\"}\n}", "name": "supressao" } ] }, { "name": "Consultar status da mensagem", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/messages\/:message", "query": [], "raw": "{{baseUrl}}\/api\/v1\/messages\/:message", "variable": [ { "id": "message", "key": "message", "value": 1, "description": "ID retornado no POST." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna o status atual e timestamps.\n\n| Status | Significado |\n|--------|-------------|\n| `pending` | Aceito; ainda na fila ou em processamento |\n| `sent` | Enviado ao provedor com sucesso |\n| `failed` | Falhou no provedor \/ transporte |\n| `skipped` | N\u00e3o enviado (ex.: higiene\/regras no worker) |\n\nID inexistente ou de outra conta \u2192 **404** (`NOT_FOUND`) \u2014 n\u00e3o revelamos dados cross-tenant." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 1,\n \"status\": \"pending\",\n \"message_type\": \"transactional\",\n \"to_email\": \"cliente@empresa.test\",\n \"subject\": \"Seu pedido #123\",\n \"scheduled_at\": \"2026-07-30T12:00:00+00:00\",\n \"sent_at\": null,\n \"created_at\": \"2026-07-30T12:00:00+00:00\",\n \"updated_at\": \"2026-07-30T12:00:00+00:00\"\n }\n}", "name": "ok" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"error\": {\"code\": \"NOT_FOUND\", \"message\": \"Recurso n\u00e3o encontrado.\"}\n}", "name": "nao_encontrada" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }