Começando

Autenticação

Como conseguir a chave de integração, trocar a chave por um token de acesso e usar, renovar e revogar esse acesso.

Toda chamada à API leva um token de acesso no header Authorization. Você gera o token no seu servidor, enviando a chave de integração ao serviço de autenticação.

Chave de integração

A chave é criada pelo administrador do grupo, no sistema VendaSimples. Cada integração tem a sua chave, que identifica a integração e define quais empresas ela acessa. A tela de integrações é só do administrador: peça a chave a ele.

O que pedir ao administrador

Nome da integração: o nome do seu sistema, para ele reconhecer a integração depois.
Empresas: quais empresas do grupo a integração deve acessar. Se nenhuma for escolhida, a integração acessa todas as empresas do grupo com contrato ativo.

Em qualquer caso, só ficam acessíveis as empresas que têm a API de Integração no contrato.

O que o administrador faz

No sistema, cria uma integração nova, com o nome e as empresas.
Grava e copia a chave gerada.
Envia a chave a você por um canal seguro.

A chave aparece uma única vez

A chave é exibida só uma vez, logo depois de gravar a integração, e não pode ser consultada depois. O administrador precisa copiá-la nesse momento. Se ela se perder, não há como gerar outra para a mesma integração: o administrador cria uma integração nova.

Trate a chave como uma senha

Guarde a chave só no servidor, nunca no navegador nem em aplicativo instalado no celular do usuário. Não a envie por e-mail ou chat em texto aberto. A chave só serve para gerar tokens: as chamadas à API usam o token.

Gerar o token

Envie a chave no corpo de um POST para o serviço de autenticação, a partir do seu servidor:

POST/auth/integracaoGerar o token de acesso Ver na referência

curl -X POST https://production.bredasapi.com.br/overall/auth/integracao \
  -H "Content-Type: application/json" \
  -d '{ "chave": "SUA_CHAVE_DE_INTEGRACAO" }'

Resposta 201 Created:

JSON

{
  "data": {
    "access_token": "3f9a1c0e7b2d4e6f8a1b2c3d4e5f6a7bbredas0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "expires_in": 1440,
    "created_date": "2026-10-23T14:00:00.1234567Z",
    "expire_date": "2026-10-24T14:00:00.1234567Z",
    "gmt_offset": -3
  }
}

Campos da resposta

Campo	Descrição
`access_token`	Token a enviar no header `Authorization` das chamadas à API
`created_date`	Quando o token foi gerado, em UTC
`expire_date`	Quando o token expira, em UTC: 24 horas depois de `created_date`
`expires_in`	Validade do token em minutos (`1440`), não em segundos
`gmt_offset`	Fuso horário do grupo, em horas em relação ao UTC (por exemplo, `-3`). Use para converter as datas da API, que vêm em UTC, para o horário do grupo

Os campos desta resposta são snake_case, diferente do resto da API, que usa camelCase. A página desse endpoint não tem o botão Testar, porque ela recebe a chave, que nunca deve ir para o navegador.

Usar o token

Envie o token no header Authorization de todas as chamadas à API, sem o prefixo Bearer. Com Bearer, a chamada é recusada com 401.

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

Em C#, DefaultRequestHeaders.Authorization exige um esquema, como Bearer. Por isso o exemplo usa TryAddWithoutValidation, que envia só o token.

Renovar o token

O token vale 24 horas. Não há renovação automática nem refresh token: quando ele expirar, gere outro com a mesma chave. Enquanto ele valer, reaproveite o mesmo token em todas as chamadas.

Guarde o expire_date e gere um token novo um pouco antes dele, ou ao receber um 401.

Gerar um token novo não invalida os anteriores: cada token vale até o próprio expire_date. Assim, mais de uma instância do seu sistema pode ter o seu token ao mesmo tempo.

O token guarda as empresas do momento

O token guarda as empresas liberadas no momento em que foi gerado, inclusive quando a integração foi criada sem empresas escolhidas. Se uma empresa for liberada para a integração, ou uma empresa nova entrar no grupo, gere um token novo para acessá-la. Se uma empresa for removida da integração, os tokens gerados antes continuam acessando essa empresa até expirar.

Revogar a chave

Se a chave vazar, peça ao administrador para revogar a integração. A revogação encerra a integração de vez: ela não volta a ficar ativa nem recebe chave nova. Para continuar integrando, o administrador cria uma integração nova, com outra chave. Depois da revogação, a chave antiga recebe 400 com "Chave de integração inválida".

O que continua valendo depois da revogação

Os tokens já gerados com a chave revogada continuam valendo até expirar, em até 24 horas. Os webhooks também continuam ativos, porque são do grupo e não da integração: se for o caso, peça ao administrador para inativá-los. Veja Webhooks.

Erros comuns

Situação	Resposta	O que fazer
Chave errada ou revogada, grupo inativo, ou nenhuma empresa da integração com contrato ativo	`400` com "Chave de integração inválida"	Confira a chave. Se ela estiver certa, fale com o administrador do grupo
Chave em branco	`400` com "Chave de integração não informada"	Envie o campo `chave` no corpo
Corpo enviado sem o header `Content-Type: application/json` na geração do token	`415` sem corpo	Envie o header `Content-Type: application/json`
Corpo ausente ou JSON inválido na geração do token	`500`	Envie `{"chave": "..."}` com o header `Content-Type: application/json`
Token com `Bearer` na frente	`401` com `{"errors":[{"errorMessage":"Unauthorized"}]}`	Envie só o token
Token ausente, expirado ou inexistente	`401` com `{"errors":[{"errorMessage":"Unauthorized"}]}`	Gere um token novo
Token válido, mas nenhuma empresa da integração tem a API de Integração no contrato, ou o token não é de uma integração (por exemplo, o de login de um usuário do sistema)	`401` sem corpo	Use um token gerado com a chave de integração. Se o erro continuar, fale com o suporte

Os outros códigos de resposta estão em Erros e limites.