Carteiro Digital API – Documentos e Pix

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:

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.
Consulte: Usuários no Invenio Center.

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.
É 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.

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

Body (JSON):

{
  "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:

{
  "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)

POST https://api.robbu.global/v2/digitalpostman

{
  "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:

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.

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:

Converta seus arquivos para Base64 antes do envio (use encoders online se necessário).

Respeite os limites de tamanho por tipo de mídia definidos pelo canal: Consulte a tabela de limites do WhatsApp no Invenio Center.

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).
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:

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:

POST https://api.robbu.global/v2/digitalpostman

{
  "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

⁉️Perguntas Frequentes (FAQ)

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.

Posso enviar mais de um documento ou anexos em um único disparo?

Sim. Adicione múltiplos objetos dentro do array documentCollection.

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.

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.

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.

Acesso

Configurações Gerais

Invenio Live

Invenio Center

Maestro