API de Integração

A API de Integração dá acesso aos dados de um grupo do VendaSimples para sistemas externos: as empresas liberadas para a integração e os pedidos em aberto (orçamentos). Ela também avisa o seu sistema por webhook quando um orçamento é criado.

Em poucas palavras

A integração deixa outro sistema que a sua empresa usa ler dados do VendaSimples sozinho, sem ninguém digitar nada de novo. Para isso, duas pessoas participam:

1. 1O administrador do grupo cria a integração no VendaSimples, escolhe as empresas e copia a chave de integração. Não precisa saber programar.
2. 2Quem programa o outro sistema usa a chave e esta documentação para ligar os dois sistemas.

Se algum termo parecer estranho (endpoint, header, JSON), veja o Glossário.

O que a API faz

A API tem dois recursos de consulta e um evento de webhook:

O evento OrcamentoCriado é enviado por webhook quando um orçamento é criado. O aviso traz o id do pedido, que você consulta no segundo recurso.

Ambiente

Há um único ambiente, o de produção. Não existe ambiente de homologação: todas as chamadas trabalham com os dados reais do grupo.

Como uma chamada é montada

Toda chamada à API segue o formato {endereço da API}/{versão}/{recurso}, com o recurso sempre no singular. A lista de empresas, por exemplo, fica em https://production.bredasapi.com.br/api/v1/empresa.

O token de acesso vai no header Authorization, sem o prefixo Bearer. Veja Autenticação.

Formato das respostas

As respostas são JSON, com nomes de campo em camelCase. A exceção é a resposta da autenticação, em snake_case (access_token, expires_in). Quando a chamada dá certo, o conteúdo vem dentro de data:

{
  "data": [
    {
      "idEmpresa": 989,
      "cpfCnpj": "11222333000181",
      "nomeRazaoSocial": "Empresa Exemplo LTDA",
      "nomeFantasia": "Exemplo"
    }
  ]
}

Quando dá errado, a resposta traz a lista errors e um sessionGuid, que identifica a chamada para o suporte. Veja Erros e limites.

• Datas vêm em UTC, no formato ISO 8601 com o sufixo Z. Para mostrar no horário do grupo, use o gmt_offset que vem na autenticação.
• Campos opcionais sem valor vêm como null; eles não são omitidos do JSON.
• Campos e valores novos podem aparecer: as respostas podem ganhar campos, e os campos de valores fixos (enums) podem ganhar valores. Ignore os campos que você não conhece e trate valores desconhecidos sem falhar. Veja Novidades da API.

Começo rápido

1. 1

   Peça a chave de integração

   O administrador do grupo cria a integração no sistema VendaSimples e envia a chave a você. Veja o que pedir a ele.

2. 2

   Gere um token

   No seu servidor, envie a chave para POST https://production.bredasapi.com.br/overall/auth/integracao. A resposta traz o access_token, que vale 24 horas. Veja Gerar o token.

3. 3

   Faça a primeira chamada

   Liste as empresas liberadas para a integração, com o token no header Authorization, como nos exemplos abaixo.

curl https://production.bredasapi.com.br/api/v1/empresa \
  -H "Authorization: SEU_TOKEN"

A resposta 200 traz as empresas dentro de data. O idEmpresa de cada uma é o mesmo que aparece no pedido e no aviso do webhook.

Fluxo de uma integração com webhook

1. 1Gere um token com a chave de integração e reaproveite-o enquanto ele valer. Veja Autenticação.
2. 2Consulte as empresas liberadas em GET /v1/empresa. O idEmpresa identifica a empresa no aviso do webhook e no pedido.
3. 3Peça ao administrador do grupo para cadastrar um webhook do evento OrcamentoCriado, com a URL do seu sistema e as empresas que interessam. Veja Webhooks.
4. 4Quando um orçamento é criado, seu sistema recebe um POST com o id do pedido. Responda 2xx logo e processe depois.
5. 5Busque os dados completos em GET /v1/pedido/{id}/aberto, com o token. Veja a referência do pedido em aberto.

Próximos passos

• Autenticação: a chave de integração, o token e como renová-lo.
• Erros e limites: formato dos erros, códigos de resposta e limite de requisições.
• Webhooks: o aviso de orçamento criado, a entrega e as novas tentativas.
• Endpoints: campos, valores e exemplos de cada um, com o botão Testar.
• Perguntas frequentes, Glossário e Novidades da API.