Este documento traz orientações para realizar a Integração com a API Bsoft.
Para esta Integração, deve ser utilizada a URL Base https://api.bsoft.com.br/sistema/v1/ para todos os endpoints.
Consulta de Conhecimentos (GET /cte)
No endpoint GET /cte, é possível retornar todos os CT-e's com base nos parâmetros passados pela url. Somente CT-e's autorizados podem ser consultados.
Parâmetros da URL
| Parâmetro | Tipo | Descrição |
|---|---|---|
| data_inicial | Date, obrigatório | Data inicial do período de emissão (formato DD/MM/AAAA), sendo esse um parâmetro obrigatório que bloqueia a consulta. |
| data_final | Date, obrigatório | Data final do período de emissão (formato DD/MM/AAAA), sendo esse um parâmetro obrigatório que bloqueia a consulta. |
| serie | String | Série dos CT-e's. |
| status | String | Lista os status dos CT-e's que deseja filtrar separados por vírgula. É possível consultar somente os status: 100, 101, 102, 110, 660, 731, 205, 301...306. Exemplo: "/cte?...&status="100,101". |
| quantidade | Integer | Quantidade máxima de registros a serem exibidos por vez. Caso esse parâmetro seja utilizado, será retornado o total de registros no cabeçalho "X-Total-Registros". |
| deslocamento | Integer | Deslocamento (offset) dos registros. |
| filtro | String | Filtro de Busca. |
| ordenacao | String | data_emissao:desc ou data_emissao:asc. |
| emita_pra_mim | Boolean | Somente emitidos via Emita Pra Mim. |
| importados | Integer | 0 - Retorna todos os CT-e's; 1 - Retorna somente os CT-e's não importados; 2 - Retorna somente os CT-e's já importados. |
| nome_integracao | String | Busca os CT-e's que tenham sido importados utilizando o "nome_integracao" para especificar o sistema da integração. Observação: Depende do argumento "importados" com o valor "2" para funcionar corretamente. |
Retorno
{
"id": 1,
"numero": 123,
"serie": 1,
"empresa": 1,
"modal": "rodoviário",
"data_emissao": "2020-03-16",
"cod_status": 100,
"motivo": "Autorizado o uso do CT-e",
"protocolo_autorizacao": "123456789012345",
"data_processamento": "2020-03-16 11:34:19",
"chave_acesso": "12345678901234567890123456789012345678901234",
"valor_total": 62.5,
"valor_icms": 0.50,
"valor_pis": 2,
"valor_cofins": 1,
"remetente": {
"nome": "BSOFT Remetente",
"cnpj_cpf": "00000000000000"
},
"destinatario": {
"nome": "BSOFT Destinatário",
"cnpj_cpf": "00000000000"
},
"pagador": {
"nome": "BSOFT Pagador",
"cnpj_cpf": "11111111111"
}
}
Consulta de Conhecimento (GET /cte/<id>)
No endpoint GET /cte/<id>, só é retornado um CT-e com as informações referentes ao mesmo.
Retorno
{
"id": 1,
"numero": 123,
"serie": 1,
"empresa": 1,
"modal": "rodoviário",
"data_emissao": "2020-03-16",
"cod_status": 100,
"motivo": "Autorizado o uso do CT-e",
"protocolo_autorizacao": "123456789012345",
"data_processamento": "2020-03-16 11:34:19",
"chave_acesso": "12345678901234567890123456789012345678901234",
"valor_total": 62.5,
"valor_icms": 0.50,
"valor_pis": 2,
"valor_cofins": 1,
"remetente": {
"nome": "BSOFT Remetente",
"cnpj_cpf": "00000000000000"
},
"destinatario": {
"nome": "BSOFT Destinatário",
"cnpj_cpf": "00000000000"
},
"pagador": {
"nome": "BSOFT Pagador",
"cnpj_cpf": "11111111111"
}
}
Consulta de Ocorrências (GET /cte/ocorrencias)
Este endpoint retorna os CT-e's e as Ocorrências vinculadas a ele com base nos parâmetros definidos. As Ocorrências emitidas para uma Nota Fiscal específica terão o atributo nota_fiscal preenchido com as informações da mesma.
Parâmetros da URL
| Parâmetro | Tipo | Descrição |
|---|---|---|
| data_inicial | Date, obrigatório | Data inicial do período de emissão da Ocorrência (formato DD/MM/AAAA), sendo esse um parâmetro obrigatório que bloqueia a consulta. |
| data_final | Date, obrigatório | Data final do período de emissão da Ocorrência (formato DD/MM/AAAA), sendo esse um parâmetro obrigatório que bloqueia a consulta. |
| nota_fiscal | String | Número da Nota Fiscal. |
Retorno
[
{
"cte": {
"id": "1",
"chave_acesso": "35000000000000000100570010251010281000000093",
"serie": "1",
"numero": "25101028",
"ocorrencias": [
{
"id": "1",
"codigo": "1",
"descricao": "Entrega realizada normalmente",
"data_hora": "2020-09-29 10:09:27",
"nota_fiscal": {
"chave_acesso": "40000000000000000000050010000789731374796462",
"serie": "78973",
"numero": "1"
}
}
]
}
}
]
Marcar CT-e Importado (PUT /cte/importacao)
Corpo da Requisição
| Parâmetro | Tipo | Descrição |
|---|---|---|
| lista_cte | Array Integer | Deve conter os id's dos CT-e's que devem ser marcados como importados. Id's inexistentes são desconsiderados juntamente com id's de CT-e's não autorizados. |
| nome_integracao | String | Nome da integração que está marcando o CT-e como importado. Se vazio, será considerada a integração padrão; caso contrário, será marcado somente para a integração informada. Um mesmo CT-e pode ser marcado como importado para diferentes integrações. |
{
"lista_cte": [1, 2, 3],
"nome_integracao": "Integracao Exemplo"
}
Retorno
Em caso de sucesso, deve ser retornado com status 200 um objeto contendo dois arrays: "lista_sucesso" (com os id's dos CT-e's que foram importados corretamente) e "lista_erro" (com os id's que não puderam ser importados, seja por não existirem, não terem sido autorizados ou já terem sido importados na integração informada no corpo da requisição).
{
"mensagem": "CT-es importados com sucesso"
"lista_sucesso": [1, 3]
"lista_erro": [2]
}
Se nenhum CT-e pôde ser importado, deve ser retornado o status 202 com dois arrays: "lista_importados" (com os id's dos CT-e's que já foram importados) e "lista_erro" (com os id's dos CT-e's que não existem ou não foram autorizados).
{
"mensagem": "CT-es já importados"
"lista_importados": [1, 2]
"lista_erro": [3]
}