> ## Documentation Index
> Fetch the complete documentation index at: https://docs.robbu.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Carteiro Digital API – Documentos e Pix

> A API Carteiro Digital, da Robbu, permite a integração para envio automatizado de documentos (como boletos, faturas, PDFs e Pix) diretamente pelo WhatsApp, garantindo autenticação segura do destinatário. Ideal para comunicações financeiras, contratuais e informativas, essa solução oferece segurança, rastreabilidade e personalização, tornando o processo de envio mais ágil e confiável.

## Autenticação

Para utilizar a **API Carteiro Digital** , é necessário obter um token de acesso `(access_token)`. Esse token deve ser solicitado através da rota de login e posteriormente enviado na requisição da **API Carteiro Digital** como `Bearer Token`, permitindo que a operação seja autorizada e executada corretamente.

> ⚠️ **Importante**:<br />
>
> * Caso o token esteja ausente, inválido ou expirado, a API retornará o erro `401 Unauthorized`, impedindo a atualização ou criação do contato.
> * O usuário utilizado na autenticação deve ser do tipo **API**, garantindo a segurança da integração e o funcionamento adequado do processo.<br /> Consulte: [Usuários no Invenio Center](https://docs.robbu.global/docs/center/usuarios).<br />
> * Não é necessário gerar um novo token a cada envio. O campo `expires_in` define sua validade em segundos e, por padrão, pode ser considerado válido por até **3333 dias**.<br /> É importante lembrar que, caso a rota de login seja **executada novamente**, o token anterior será **invalidado**. Por isso, a recomendação é armazená-lo e solicitar um novo apenas quando a requisição de envio retornar `401 Unauthorized`.

### Endpoint de Login

* **Método:** `POST`
* **URL:** `https://api.robbu.global/v1/login`

Body (JSON):

```json theme={null}
{
  "Company": "NOME_DA_EMPRESA",
  "Username": "USUARIO_API",
  "Password": "SENHAUSUARIO_API"
}
```

Campos:

* `Company`: Nome do ambiente/empresa no Invenio Center.
* `Username`: Usuário com permissão de integração (tipo API).
* `Password`: Senha do usuário.

Exemplo de response de login:

```json theme={null}
{
  "access_token": "eyJhbGciOi...",
  "expires_in": 287971200,
  "refresh_token": "",
  "token_type": "bearer"
}
```

***

## Endpoint de Envio de Documento

* **Método:** `POST`
* **URL:** `https://api.robbu.global/v2/digitalpostman`

O envio deve incluir o cabeçalho `Authorization: Bearer {access_token}`.

**Exemplo de request (completo)**

```json title="POST https://api.robbu.global/v2/digitalpostman" showLineNumbers theme={null}
{
  "senderName": "Robbu",
  "contactName": "Robbu Teste",
  "contactId": "11122233344",
  "walletCode": "CarteiraTeste",
  "contactPhoneNumber": "5511999999999",
  "invalidTokenMessage": "Opção inválida!\r\n\r\nAqui estão os nossos canais de atendimento:\r\n📞551199999999",
  "instructionsMessage": "*Tem dúvidas? Fale com a Robbu:😀*\r\n📞551199999999",
  "documentCollection": [
    {
      "documentCode": "1946753214860",
      "documentFileName": "boleto.pdf",
      "documentBase64": "JVBERi0xLjMKJcTl8uXrp..."
    }
  ]
}
```

***

## Detalhamento dos Campos

| **Campo**             | **Descrição**                                                          |
| --------------------- | ---------------------------------------------------------------------- |
| `senderName`          | Nome do remetente exibido ao destinatário.                             |
| `contactName`         | Nome completo do destinatário.                                         |
| `contactId`           | CPF/CNPJ do destinatário — usado para validação (3 primeiros dígitos). |
| `walletCode`          | Código da carteira cadastrada no Invenio.                              |
| `contactPhoneNumber`  | Número do destinatário com DDI + DDD (ex.: `5511999999999`).           |
| `invalidTokenMessage` | Mensagem exibida quando o token informado pelo usuário for inválido.   |
| `instructionsMessage` | Mensagem com instruções enviada junto ao documento disparado.          |
| `documentCollection`  | Array com os documentos a serem enviados (veja estrutura abaixo).      |

> ⚠️ **Importante**:<br />
>
> * Com exceção dos campos `invalidTokenMessage` e `instructionsMessage`, nenhuma outra mensagem ou frase exibida durante a jornada do contato pode ser personalizada, além dos próprios campos **variáveis da integração**. Esses dois campos são os únicos que permitem customização textual completa. <br />
>
> * Além disso, para ambos é possível inserir **emojis** diretamente no código, bem como realizar **quebras de linha** utilizando os caracteres `\r\n`, garantindo maior flexibilidade na formatação da comunicação.

### Estrutura do campo `documentCollection`

| **Campo**          | **Tipo** | **Obrigatório** | **Descrição**                                                         |
| ------------------ | -------- | --------------- | --------------------------------------------------------------------- |
| `documentCode`     | String   | Sim             | Linha digitável do boleto ou identificador do documento / código Pix. |
| `documentFileName` | String   | Sim             | Nome do arquivo (ex.: `boleto.pdf`, `qrcode.png`).                    |
| `documentBase64`   | String   | Sim             | Arquivo codificado em Base64.                                         |
| `documentValue`    | String   | Não (Pix: Sim)  | Valor do documento — obrigatório para envios de Pix.                  |

> ⚠️ **Observações**:<br />
>
> * Converta seus arquivos para Base64 antes do envio (use encoders online se necessário).<br />
> * Respeite os limites de tamanho por tipo de mídia definidos pelo canal: [Consulte a tabela de limites do WhatsApp no Invenio Center](https://docs.robbu.global/docs/center/canal-whatsapp#m%C3%ADdias-suportadas).

***

## Responses

| **Código**                  | **Descrição**                                      |
| --------------------------- | -------------------------------------------------- |
| `200 OK`                    | Requisição processada com sucesso; envio iniciado. |
| `400 Bad Request`           | Parâmetros inválidos ou incompletos.               |
| `401 Unauthorized`          | Token ausente, inválido ou expirado.               |
| `404 Not Found`             | URL incorreta.                                     |
| `500 Internal Server Error` | Erro interno da API.                               |

> A API pode não retornar detalhes de erros de provedores externos (**Por exemplo:** `Meta/WhatsApp`).<br /> Para logs e detalhes de entrega, verifique o **Invenio Center**.

***

## Fluxo de Validação por Token

Ao enviar o documento, o usuário destinatário precisa validar o acesso informando os **3 primeiros dígitos** do `contactId` (CPF/CNPJ). Se a validação for correta, o arquivo é disponibilizado.

> ⚠️ **Observação sobre CPFs iniciados por zero:**<br />
>
> * Para CPFs que começam com `0`, aceitamos a digitação dos três dígitos com ou sem o zero inicial. Ex.: `011.222.333-44` aceita `011` ou `112`.

***

## Exemplos de uso

* Envio de documento (boleto) — já mostrado acima.
* Envio de Pix — neste caso inclua `documentValue` com o valor do pagamento no objeto do `documentCollection`.

**Exemplo:**

```json title="POST https://api.robbu.global/v2/digitalpostman" showLineNumbers theme={null}
{
  "senderName": "Robbu",
  "contactName": "Robbu Teste",
  "contactId": "11122233344",
  "walletCode": "c141",
  "contactPhoneNumber": "5511998037663",
  "invalidTokenMessage": "Opção inválida!\r\n\r\nAqui estão os nossos canais de atendimento:\r\n📞551199999999",
  "instructionsMessage": "*Tem dúvidas? Fale com a Robbu:😀*\r\n📞551199999999",
  "documentCollection": [
    {
      "documentCode": "c9f1a3b4-82d7-4e0e-9a21-55f4d7b98f10",
      "documentValue": "1200.00",
      "documentFileName": "pix-qrcode.png",
      "documentBase64": "..."
    }
  ]
}
```

***

## 🔗 Links e assuntos relacionados

* [Configurações Gerais da Conta](https://docs.robbu.global/docs/center/configuracoes-gerais-da%20conta)
* [Usuários no Invenio Center](https://docs.robbu.global/docs/center/usuarios)
* [Canal de WhatsApp — limites por tipo de mídia](https://docs.robbu.global/docs/center/canal-whatsapp#tabela-de-limites-por-tipo-de-midia)
* [API Send Message](https://docs.robbu.global/docs/robbu-api/send-message)
* [Segmentos no Invenio Center](https://docs.robbu.global/docs/center/segmentos)
* [Canal de WhatsApp (visão geral)](https://docs.robbu.global/docs/center/canal-whatsapp)
* [Enviar mensagem (Invenio Live)](https://docs.robbu.global/docs/live/enviar-mensagem)

***

## ⁉️Perguntas Frequentes (FAQ)

<AccordionGroup>
  <Accordion title="O token de autenticação precisa ser gerado para cada requisição?">
    Não. Guarde o `access_token` até expirar ou até a API retornar `401 Unauthorized`.
  </Accordion>

  <Accordion title="Posso enviar mais de um documento ou anexos em um único disparo?">
    Sim. Adicione múltiplos objetos dentro do array `documentCollection`.
  </Accordion>

  <Accordion title="Como faço para converter meu arquivo para Base64 antes do envio?">
    Utilize qualquer conversor online ou uma biblioteca local para gerar o Base64 do arquivo antes de enviar.
  </Accordion>

  <Accordion title="O que acontece se o usuário informar o token de validação incorreto?">
    A mensagem definida em `invalidTokenMessage` será exibida; você pode personalizá-la conforme o fluxo desejado.
  </Accordion>

  <Accordion title="Qual a diferença entre envio de documento e envio de Pix?">
    Sim. Para Pix, `documentValue` é obrigatório e deve conter o valor associado ao pagamento.
  </Accordion>
</AccordionGroup>

***