Ir para o conteúdo

Wiki de Integração de Certificadoras – API SISBOV 2

Índice de Tópicos

# Tópico Itens
1 Arquitetura e Conceitos Gerais 10
2 Segurança e Autenticação 7
3 Estrutura das Requisições 3
4 Códigos de Retorno HTTP 2
5 Rastreabilidade SISBOV 4
6 ERAS – Estabelecimento Rural Aprovado 3
7 Modelo de Entidades 3
8 Campos Obrigatórios em Payloads 3
9 Exemplos de Payload 4
10 Tipos e Enums 5
11 Fluxos Operacionais 6
12 Qualidade de Dados e Boas Práticas 3
13 Ambientes e Versionamento 3
Total 56

1. Arquitetura e Conceitos Gerais

1.1 Qual é o objetivo principal da API de integração do SISBOV 2 para certificadoras?

Resposta: Permitir a comunicação automatizada entre os sistemas das certificadoras e o sistema SISBOV, possibilitando o registro, consulta e atualização de informações de rastreabilidade de animais e propriedades, garantindo padronização, integridade e auditoria das informações registradas.

1.2 Qual o modelo de comunicação utilizado pela API?

Resposta: RESTful API

1.3 Quais são os princípios REST respeitados pela API?

Resposta:

  • Comunicação stateless
  • Recursos identificados por URI
  • Uso de métodos HTTP padronizados (GET, POST, PUT, DELETE)
  • Representação em JSON
  • Cacheabilidade quando aplicável

1.4 O que significa o princípio stateless em APIs REST?

Resposta: Cada requisição contém todas as informações necessárias para ser processada, sem dependência de estado de sessão no servidor. Permite escalabilidade horizontal, reduz dependência de sessão e facilita balanceamento de carga.

1.5 Qual formato de dados é utilizado nas requisições e respostas da API?

Resposta: JSON

1.6 O que representa o conceito de produtor no modelo de dados do SISBOV?

Resposta: Pessoa física ou jurídica responsável pela criação e manejo dos animais vinculados ao sistema de rastreabilidade.

1.7 O que representa uma propriedade dentro do sistema?

Resposta: Unidade rural vinculada a um produtor onde ocorre a criação ou manejo de animais registrados no SISBOV.

1.8 O que representa um proprietário dentro do sistema?

Resposta: Detentor legal da propriedade rural.

1.9 Qual é a relação entre Produtor, Propriedade e Animal?

Resposta:

  • O produtor é o responsável legal pela atividade pecuária.
  • O produtor possui uma ou mais propriedades.
  • A propriedade possui um ou mais animais registrados no SISBOV.

1.10 O que significa idempotência em APIs?

Resposta: Uma requisição idempotente pode ser executada múltiplas vezes sem alterar o resultado final. Evita duplicidade de registros quando ocorrem reenvios de requisição por falhas de rede.

Exemplos de operações idempotentes: GET, PUT, DELETE.

2. Segurança e Autenticação

2.1 Qual método de autenticação é utilizado para acesso à API?

Resposta: Autenticação baseada em token de acesso (Bearer Token) obtido via endpoint auth/system, informando os headers X-ACCESS-KEY e X-SECRET-KEY.

Authorization: Bearer {access_token}

⚠️ O uso do WSO2 foi removido da API.

2.2 O que representa um token de acesso no contexto da API?

Resposta: Credencial digital temporária que comprova a identidade do cliente da API e permite acesso aos recursos autorizados.

2.3 Qual a finalidade do header Authorization nas requisições HTTP?

Resposta: Transportar o token de autenticação que autoriza o cliente a acessar a API.

Authorization: Bearer {access_token}
Content-Type: application/json

2.4 Qual é a principal diferença entre autenticação e autorização?

Resposta:

  • Autenticação → verifica quem é o usuário/sistema
  • Autorização → define o que ele pode acessar

2.5 Por que é importante utilizar HTTPS nas chamadas da API?

Resposta:

  • Garante criptografia da comunicação
  • Protege dados sensíveis contra interceptação
  • Garante integridade da comunicação

2.6 O que deve ser feito quando um token de acesso expira?

Resposta: Solicitar um novo token de acesso através do endpoint auth/system antes de realizar novas chamadas.

2.7 O que ocorre se uma requisição for enviada sem token?

Resposta: A API retorna HTTP 401 – Unauthorized (falha de autenticação).

3. Estrutura das Requisições

3.1 Quais são os principais métodos HTTP utilizados na API?

Método Uso
GET Consulta de dados
POST Criação de registros
PUT Atualização
DELETE Remoção

3.2 O que é um Request Payload?

Resposta: Corpo da requisição enviado pelo cliente contendo os dados da operação, no formato JSON.

3.3 O que é um Response Payload?

Resposta: Corpo da resposta retornada pela API após o processamento da requisição.

4. Códigos de Retorno HTTP

4.1 Tabela de Códigos HTTP

Código Significado
200 Sucesso
201 Recurso criado com sucesso
400 Erro de validação na requisição
401 Falha de autenticação (token inválido)
403 Acesso proibido (não autorizado)
404 Recurso não encontrado
417 Erro de regra de negócio SISBOV
500 Erro interno do servidor

4.2 O que significa o retorno 417 (Expectation Failed) na API SISBOV?

Resposta: Indica que a requisição foi tecnicamente recebida, porém falhou em validações de regra de negócio ou integridade de dados exigidas pelo sistema SISBOV. O retorno sempre vem acompanhado do texto descritivo do erro.

Exemplos de situações que geram 417:

  • Número SISBOV inválido ou duplicado
  • ERAS inexistente ou inválido
  • Animal já registrado no sistema
  • Inconsistência de rastreabilidade
  • Data inválida

5. Rastreabilidade SISBOV

5.1 O que é o Número SISBOV?

Resposta: Identificador único e individual de rastreabilidade atribuído ao animal dentro do sistema SISBOV. Não pode ser reutilizado.

5.2 Quais são os tipos de Número SISBOV?

Tipo Descrição
076 Identificação padrão SISBOV (novos cadastros)
105 Identificação derivada, reidentificação ou estoque legado

Novas solicitações de numeração geram apenas números padrão 076.

5.3 Por que o Número SISBOV é crítico para auditorias internacionais?

Resposta: Porque garante rastreabilidade individual do animal ao longo de toda a cadeia produtiva, sendo exigido em auditorias sanitárias e processos de exportação de carne.

5.4 O que representa um evento na vida do animal dentro do sistema?

Resposta: Registro de um acontecimento relevante no ciclo de vida do animal.

Exemplos de eventos:

  • Nascimento / Identificação
  • Movimentação entre propriedades
  • Entrada em frigorífico
  • Morte
  • Desligamento
  • Reidentificação

6. ERAS – Estabelecimento Rural Aprovado no SISBOV

6.1 O que é ERAS?

Resposta: Estabelecimento Rural Aprovado no SISBOV — identificador oficial atribuído a propriedades rurais habilitadas no sistema de rastreabilidade.

6.2 O que representa o codigoEras?

Resposta: Identificador da propriedade oficialmente habilitada no SISBOV. Utilizado para:

  • Registro de animal
  • Movimentação entre propriedades
  • Vinculação de eventos

6.3 Um animal pode existir sem ERAS?

Resposta: Não. O codigoEras é obrigatório no cadastro do animal. Se o ERAS for inválido, a API retorna HTTP 417.

7. Modelo de Entidades

7.1 Qual a diferença entre Produtor e Proprietário?

Entidade Descrição
Produtor Responsável pela atividade pecuária e manejo dos animais
Proprietário Detentor legal da propriedade rural

Um produtor pode estar vinculado a várias propriedades e vice-versa. São cadastros independentes — não há hierarquia ou prioridade de criação.

7.2 Como vincular Produtor a uma Propriedade?

Resposta:

propriedade/{id}/vincularProdutor/{idProdutor}
propriedade/{id}/desvincularProdutor/{idProdutor}

7.3 O campo isProprietario do Produtor — o que significa?

Resposta: Indica se o Produtor é também proprietário de uma Propriedade. Se informado true, será cadastrado automaticamente um Proprietário que poderá ser localizado pelo identificadorReceita (chave natural).

8. Campos Obrigatórios em Payloads

8.1 Campos obrigatórios típicos para cadastro de animal

Campo Obrigatório
numeroSisbov ✅ Sim
codigoEras ✅ Sim
sexoAnimal ✅ Sim
dataNascimento ✅ Sim
dataIdentificacao ✅ Sim
codigoRaca ✅ Sim (consultar tabela de domínio)

8.2 O que ocorre se um campo obrigatório estiver ausente?

Resposta: A requisição é rejeitada com HTTP 400 – Bad Request (erro de validação).

8.3 O que ocorre se um campo possuir valor inválido?

Resposta: A API retorna HTTP 417 – Expectation Failed (erro de regra de negócio).

9. Exemplos de Payload

9.1 Payload válido — cadastro de animal

POST /animais

{
  "numeroSisbov": "076123456789012",
  "codigoEras": "ERAS12345",
  "sexoAnimal": "M",
  "dataNascimento": "2022-05-10"
}

Resposta esperada: HTTP 201 Created

9.2 Payload inválido — campo obrigatório ausente

{
  "codigoEras": "ERAS12345",
  "sexoAnimal": "M"
}

Erro esperado: HTTP 400 — campo numeroSisbov ausente.

9.3 Payload inválido — ERAS inexistente

{
  "numeroSisbov": "076123456789012",
  "codigoEras": "ERAS99999",
  "sexoAnimal": "F",
  "dataNascimento": "2021-03-15"
}

Erro esperado: HTTP 417 — ERAS inexistente ou inválido.

9.4 Payload inválido — SISBOV duplicado

{
  "numeroSisbov": "076123456789012",
  "codigoEras": "ERAS12345"
}

Erro esperado: HTTP 417 — animal já registrado.

10. Tipos e Enums

10.1 TipoIdentificacao

Consultar Enum na sessão Schema do Swagger.

Valores documentados: BR, BRINCO, BRINCO_BOTON, BRINCO_DISPOSITIVO, BO, BRBO, BRTA, DEIV, TAMF, BRDE, VIVO, RIN, ASSRA, BOMF, MIGR, BRMF, BRBOF

10.2 TipoEntradaAnimal

Valor Quando usar
NASCIMENTO Identificação no nascimento
ENTRADA Entrada a partir de propriedade não ERAS
REINDENTIFICACAO Reidentificação por mudança de elemento de identificação
CARGA_INICIAL Portabilidade — não utilizado pelas certificadoras
DADOS_MIGRADOS Portabilidade — não utilizado pelas certificadoras

10.3 StatusAnimal

Consultar Enum na sessão Schema do Swagger.

Valores: VIVO, MORTO, ABATIDO, ABATIDO_PARA_EXPORTACAO, DESLIGADO, EM_FRIGORIFICO, EM_TRANSITO, APTO_PARA_ABATE_PARA_EXPORTACAO, CALHA_SANGRIA

Os status CALHA_SANGRIA e APTO_PARA_ABATE_PARA_EXPORTACAO são exclusivos do contexto de frigoríficos.

10.4 TipoGTA

Valor Quando usar
PADRAO GTA utilizada para Movimentações entre propriedades
SEM_IDENTIFICACAO_ORIGEM GTA de entrada de animais originados de propriedade não ERAS

10.5 TipoTransporte

Consultar Enum na sessão Schema do Swagger.

Valores: CAMINHAO, CARAVANA, A_PE, RODOVIARIO, MARITMO_FLUVIAL, AEREO

11. Fluxos Operacionais

11.1 Fluxo completo de cadastro de animal via API

  1. Autenticação (auth/system) — obter Bearer Token
  2. Validação local dos dados do animal
  3. Verificar validade do codigoEras
  4. Envio do payload via POST /animais
  5. Validação pelo sistema SISBOV
  6. Retorno do identificador do animal (HTTP 201)

11.2 Fluxo completo de Movimentação entre Propriedades

Ações da origem: 1. Criar movimentação 2. Informar GTAs 3. Adicionar animais 4. Iniciar movimentação → PUT /movimentacao/{id}/iniciarMovimentacao

Ações do destino: 5. Finalizar movimentação → PUT /movimentacao/{id}/finalizarMovimentacaoEntrePropriedades

Os animais alteram propriedadeLocalização e produtor somente após a finalização. Após finalizada, a movimentação não pode ser cancelada.

11.3 Fluxo de Movimentação para Frigorífico

Similar à Movimentação entre Propriedades, porém informa o Frigorífico de destino (CNPJ ou SIF) em vez de Produtor e Propriedade.

A responsabilidade da certificadora vai até o iniciarMovimentacao. A partir deste ponto, a responsabilidade é do Frigorífico de destino.

11.4 Fluxo de Registro de Morte

PUT /animal/{id}/registraMorte/{idCausaMorte}/{dataMorte}

Processado um animal por vez. Para obter idCausaMorte: GET /util/dominio/listDominio/{dominio}

11.5 Fluxo de Realização de Vistoria

POST /vistoria
GET /vistoria/{id}/listarPerguntas
PUT /vistoria/resposta/{idResposta}/responderAtualizar/{opcaoSelecionada}
PUT /vistoria/{id}/aprovar/{parecer}

O endpoint PUT /vistoria/{id}/realizar não existe.

11.6 Fluxo de solicitação de numeração

Até 20.000 números solicitados → aprovação automática pelo sistema. Acima disso → aprovação deve ser solicitada à SDA.

GET /solicitacaoNumeracao/listFabricas   → listar fábricas disponíveis

Campo idFaixaDeNumeracao: não preencher. Campo idUsuarioSolicitante: extraído automaticamente do token JWT.

12. Qualidade de Dados e Boas Práticas

12.1 Por que validar os dados antes de enviá-los?

Resposta: Para evitar rejeição da requisição, garantir consistência da base de dados e evitar erros que comprometam a rastreabilidade ou auditorias de exportação.

12.2 Boas práticas de integração

✅ Validar payload localmente antes do envio ✅ Tratar corretamente os códigos de erro HTTP ✅ Implementar retry controlado (com idempotência) ✅ Registrar logs completos de cada requisição ✅ Proteger credenciais de acesso (nunca expor tokens em logs) ✅ Verificar validade do ERAS antes de enviar requisição ✅ Consultar tabelas de domínio via /util/dominio/listDominio/{dominio}

12.3 O que deve ser registrado nos logs de integração?

Resposta:

  • Endpoint chamado
  • Data e hora (timestamp)
  • Identificador da requisição
  • Payload enviado
  • Resposta da API
  • Código de status HTTP

13. Ambientes e Versionamento

13.1 URLs dos ambientes

Ambiente URL
Homologação https://api-cert-hmg-sisbov.agricultura.gov.br
Produção Sufixo sisbov.agricultura.gov.br

13.2 Processo de Homologação

  1. Acesso ao ambiente de homologação
  2. Execução de cenários de teste obrigatórios
  3. Validação técnica dos resultados
  4. Auditoria da integração (logs)
  5. Liberação para produção

Testes mínimos obrigatórios:

Teste Resultado esperado
Cadastro válido 201
Campo ausente 400
ERAS inválido 417
SISBOV duplicado 417
Token inválido 401

13.3 Política de versionamento

A API adota Versionamento Semântico (MAJOR.MINOR.PATCH).

  • MAJOR → mudanças que quebram compatibilidade (requer migração)
  • MINOR → novas funcionalidades retrocompatíveis
  • PATCH → correções internas

Evoluções ocorrem primeiramente em homologação. Em produção haverá somente uma versão ativa. O changelog está disponível na documentação auxiliar da API.