Tem Dentista OpenAPI

API da vigilância sanitária · v1.0.0

Tem Dentista para desenvolvedores

Visão geral

A API da vigilância sanitária do Tem Dentista é aberta, gratuita e igual para todo o Brasil. Qualquer sistema usado por uma vigilância sanitária, municipal ou estadual, seja próprio da prefeitura ou contratado de uma empresa, pode se ligar nela para ler a ficha sanitária das clínicas odontológicas da sua área.

A API mostra exatamente o que o fiscal vê no portal da vigilância: só as clínicas da cidade (ou do estado, na vigilância estadual) que ligaram o compartilhamento, e só os itens que cada clínica escolheu mostrar. Nunca sai dado de paciente nem dado pessoal ou de saúde da equipe. É só leitura, e a clínica vê cada consulta feita pelo sistema.

Endereço base
https://app.temdentista.com.br/api/v1/vigilancia
Formato
JSON (UTF-8), só leitura (GET)
Custo
Gratuita

Como pedir acesso

1. Quem pede é a vigilância sanitária. Um fiscal entra no portal da vigilância com o e-mail do órgão e abre "Integração com sistema".
2. Lá ele escreve o nome do sistema (por exemplo, "Sistema de fiscalização da Prefeitura") e gera uma chave de acesso. A chave aparece uma vez só.
3. A vigilância passa a chave para a equipe ou empresa que cuida do sistema dela. Cada sistema deve ter a sua chave.
4. A chave pode ser revogada a qualquer momento pela própria vigilância. Revogada, o acesso para na hora.

Antes de ter a chave, use o ambiente de testes abaixo: ele responde com clínicas de exemplo, no mesmo formato da resposta real.

Portal da vigilância: https://app.temdentista.com.br/vigilancia

Autenticação

Toda chamada leva a chave no cabeçalho Authorization. A chave começa com tdv_ e é do órgão de vigilância: ela define a área (a cidade ou o estado) que o sistema enxerga. Também aceitamos o cabeçalho X-Api-Key.

Authorization: Bearer tdv_…
  • Guarde a chave como senha: em variável de ambiente ou cofre de segredos, nunca no código nem no navegador.
  • Só HTTPS. Chamadas sem chave, com chave errada ou revogada recebem 401.
  • A vigilância vê o último uso de cada chave e pode revogá-la a qualquer momento.

Ambiente de testes

Use a chave de teste abaixo no mesmo endereço da API. Ela não depende de cadastro e responde com 4 clínicas de exemplo em “Cidade de Exemplo/SP”, uma em cada situação, no mesmo formato da resposta real (inclusive a Pasta do fiscal e os arquivos). A resposta traz o cabeçalho X-Api-Ambiente: testes.

Ids das clínicas de exemplo: 900001, 900002, 900003, 900004.

Referência das rotas

Todas as rotas são GET e começam com https://app.temdentista.com.br/api/v1/vigilancia.

GET /eu

Quem é a chave

Órgão dono da chave, ambiente (producao ou testes), limite por minuto e versão. Bom para testar a ligação.

Requisição

curl -H "Authorization: Bearer tdv_teste_clinicas_de_exemplo" "https://app.temdentista.com.br/api/v1/vigilancia/eu"

Resposta 200

{
    "data": {
        "ambiente": "testes",
        "orgao": {
            "id": 0,
            "nome": "Vigilância Sanitária de Exemplo",
            "esfera": "municipal",
            "uf": "SP",
            "cidade": "Cidade de Exemplo",
            "codigo_ibge": null,
            "area": "Cidade de Exemplo/SP"
        },
        "chave": {
            "nome_sistema": "Chave de teste",
            "prefixo": "tdv_teste_",
            "criada_em": null,
            "avisos": false
        },
        "limite_por_minuto": 60,
        "versao": "1.0.0"
    }
}

Erros possíveis: 401, 403, 429, 503. Veja Erros.

GET /clinicas

Listar clínicas

Clínicas da área do órgão com o compartilhamento ligado, em ordem de id. Clínica que desliga some da lista na hora.

ParâmetroOndeO que é
pagina consulta Página (começa em 1).
por_pagina consulta Itens por página (até 100).
situacao consulta Só as clínicas nesta situação. Valores: em_dia, atencao, atrasada, sem_informacao.
atualizado_desde consulta Só as clínicas com mudança na ficha desde esta data (AAAA-MM-DD ou ISO 8601).

Requisição

curl -H "Authorization: Bearer tdv_teste_clinicas_de_exemplo" "https://app.temdentista.com.br/api/v1/vigilancia/clinicas?situacao=atencao&por_pagina=25"

Resposta 200

{
    "data": [
        {
            "id": 900001,
            "nome": "Clínica de Exemplo Sorriso",
            "cidade": "Cidade de Exemplo",
            "uf": "SP",
            "codigo_ibge": null,
            "cnes": "1234561",
            "situacao": "em_dia",
            "em_dia": {
                "ok": 18,
                "fazer": 0,
                "atrasado": 0
            },
            "licenca": {
                "estado": "ok",
                "vale_ate": "2027-07-22",
                "dias": 242
            },
            "blocos_liberados": [
                "dados",
                "responsavel",
                "licencas",
                "pops",
                "autoclave",
                "pgrss",
                "pasta"
            ],
            "compartilhando_desde": "2026-09-23T09:30:00-03:00",
            "atualizado_em": "2026-11-21T16:10:00-03:00",
            "links": {
                "ficha": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001"
            }
        },
        {
            "id": 900002,
            "nome": "Clínica de Exemplo Centro",
            "cidade": "Cidade de Exemplo",
            "uf": "SP",
            "codigo_ibge": null,
            "cnes": "1234562",
            "situacao": "atencao",
            "em_dia": {
                "ok": 15,
                "fazer": 2,
                "atrasado": 0
            },
            "licenca": {
                "estado": "fazer",
                "vale_ate": "2026-12-12",
                "dias": 20
            },
            "blocos_liberados": [
                "dados",
                "responsavel",
                "licencas",
                "pops"
            ],
            "compartilhando_desde": "2026-10-23T09:30:00-03:00",
            "atualizado_em": "2026-11-17T16:10:00-03:00",
            "links": {
                "ficha": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900002"
            }
        }
    ],
    "meta": {
        "pagina": 1,
        "por_pagina": 2,
        "total": 4,
        "ultima_pagina": 2
    },
    "links": {
        "anterior": null,
        "proxima": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas?por_pagina=2&pagina=2"
    }
}

Erros possíveis: 401, 403, 429, 503, 422. Veja Erros.

GET /clinicas/{clinica}

Ficha da clínica

A ficha sanitária com os blocos liberados pela clínica. Bloco não liberado não aparece em "blocos".

ParâmetroOndeO que é
clinica* caminho id da clínica (o campo id da lista).

Requisição

curl -H "Authorization: Bearer tdv_teste_clinicas_de_exemplo" "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001"

Resposta 200

{
    "data": {
        "id": 900001,
        "nome": "Clínica de Exemplo Sorriso",
        "cidade": "Cidade de Exemplo",
        "uf": "SP",
        "codigo_ibge": null,
        "situacao": "em_dia",
        "blocos_liberados": [
            "dados",
            "responsavel",
            "licencas",
            "pops",
            "autoclave",
            "pgrss",
            "pasta"
        ],
        "compartilhando_desde": "2026-09-23T09:30:00-03:00",
        "atualizado_em": "2026-11-21T16:10:00-03:00",
        "blocos": {
            "dados": {
                "cnpj": "00.000.000/0001-00",
                "cnes": "1234561",
                "endereco": "Rua de Exemplo, 100 - Centro - Cidade de Exemplo/SP",
                "telefone": "(11) 3000-0001",
                "email": "[email protected]"
            },
            "responsavel": {
                "rt_nome": "Responsável Técnico de Exemplo 1",
                "rt_cro": "CRO-SP 000001",
                "rt_substituto": "Substituto de Exemplo",
                "responsavel_legal": "Responsável Legal de Exemplo 1",
                "supervisor_radiologica": "Responsável Técnico de Exemplo 1"
            },
            "licencas": {
                "licenca": {
                    "estado": "ok",
                    "vale_ate": "2027-07-22",
                    "dias": 242
                },
                "documentos": [
                    {
                        "tipo": "licenca_sanitaria",
                        "rotulo": "Licença sanitária",
                        "documento_id": 9000011,
                        "numero": "01/2026",
                        "orgao": "Vigilância Sanitária de Exemplo",
                        "emitido_em": "2026-07-22",
                        "vence_em": "2027-07-22",
                        "situacao": "Em dia",
                        "tem_arquivo": true,
                        "arquivo_url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/documentos/9000011"
                    },
                    {
                        "tipo": "alvara",
                        "rotulo": "Alvará de funcionamento",
                        "documento_id": 9000012,
                        "numero": "ALV-12026",
                        "orgao": "Prefeitura de Exemplo",
                        "emitido_em": "2025-11-22",
                        "vence_em": null,
                        "situacao": "Sem validade",
                        "tem_arquivo": true,
                        "arquivo_url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/documentos/9000012"
                    },
                    {
                        "tipo": "vacinacao",
                        "rotulo": "Comprovantes de vacinação da equipe",
                        "documento_id": 9000013,
                        "numero": null,
                        "orgao": null,
                        "emitido_em": "2026-09-22",
                        "vence_em": null,
                        "situacao": "Sem validade",
                        "tem_arquivo": false,
                        "arquivo_url": null
                    },
                    {
                        "tipo": "contrato_residuos",
                        "rotulo": "Contrato de coleta de resíduos",
                        "documento_id": null,
                        "numero": null,
                        "orgao": null,
                        "emitido_em": null,
                        "vence_em": null,
                        "situacao": "Não guardado",
                        "tem_arquivo": false,
                        "arquivo_url": null
                    }
                ]
            },
            "pasta": {
                "id": 9000010,
                "gerada_em": "2026-11-19T14:00:00-03:00",
                "de": "2025-11-22",
                "ate": "2026-11-19",
                "zip_url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta",
                "itens": [
                    {
                        "n": 0,
                        "parte": "Manual de POPs",
                        "titulo": "Manual de POPs",
                        "detalhe": "19 POPs aprovados",
                        "arquivo": "manual-de-pops.pdf",
                        "url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta/0"
                    },
                    {
                        "n": 2,
                        "parte": "Autoclave",
                        "titulo": "Testes da autoclave",
                        "detalhe": "12 meses",
                        "arquivo": "testes-da-autoclave.pdf",
                        "url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta/2"
                    },
                    {
                        "n": 5,
                        "parte": "Pasta da vigilância",
                        "titulo": "Lista dos documentos",
                        "detalhe": null,
                        "arquivo": "lista-dos-documentos.pdf",
                        "url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta/5"
                    }
                ]
            }
        },
        "links": {
            "ficha": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001",
            "pops": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pops",
            "pasta": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta"
        }
    }
}
Ver a ficha inteira, com todos os blocos
{
    "data": {
        "id": 900001,
        "nome": "Clínica de Exemplo Sorriso",
        "cidade": "Cidade de Exemplo",
        "uf": "SP",
        "codigo_ibge": null,
        "situacao": "em_dia",
        "blocos_liberados": [
            "dados",
            "responsavel",
            "licencas",
            "pops",
            "autoclave",
            "pgrss",
            "pasta"
        ],
        "compartilhando_desde": "2026-09-23T09:30:00-03:00",
        "atualizado_em": "2026-11-21T16:10:00-03:00",
        "blocos": {
            "dados": {
                "cnpj": "00.000.000/0001-00",
                "cnes": "1234561",
                "endereco": "Rua de Exemplo, 100 - Centro - Cidade de Exemplo/SP",
                "telefone": "(11) 3000-0001",
                "email": "[email protected]"
            },
            "responsavel": {
                "rt_nome": "Responsável Técnico de Exemplo 1",
                "rt_cro": "CRO-SP 000001",
                "rt_substituto": "Substituto de Exemplo",
                "responsavel_legal": "Responsável Legal de Exemplo 1",
                "supervisor_radiologica": "Responsável Técnico de Exemplo 1"
            },
            "licencas": {
                "licenca": {
                    "estado": "ok",
                    "vale_ate": "2027-07-22",
                    "dias": 242
                },
                "documentos": [
                    {
                        "tipo": "licenca_sanitaria",
                        "rotulo": "Licença sanitária",
                        "documento_id": 9000011,
                        "numero": "01/2026",
                        "orgao": "Vigilância Sanitária de Exemplo",
                        "emitido_em": "2026-07-22",
                        "vence_em": "2027-07-22",
                        "situacao": "Em dia",
                        "tem_arquivo": true,
                        "arquivo_url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/documentos/9000011"
                    },
                    {
                        "tipo": "alvara",
                        "rotulo": "Alvará de funcionamento",
                        "documento_id": 9000012,
                        "numero": "ALV-12026",
                        "orgao": "Prefeitura de Exemplo",
                        "emitido_em": "2025-11-22",
                        "vence_em": null,
                        "situacao": "Sem validade",
                        "tem_arquivo": true,
                        "arquivo_url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/documentos/9000012"
                    },
                    {
                        "tipo": "vacinacao",
                        "rotulo": "Comprovantes de vacinação da equipe",
                        "documento_id": 9000013,
                        "numero": null,
                        "orgao": null,
                        "emitido_em": "2026-09-22",
                        "vence_em": null,
                        "situacao": "Sem validade",
                        "tem_arquivo": false,
                        "arquivo_url": null
                    },
                    {
                        "tipo": "contrato_residuos",
                        "rotulo": "Contrato de coleta de resíduos",
                        "documento_id": null,
                        "numero": null,
                        "orgao": null,
                        "emitido_em": null,
                        "vence_em": null,
                        "situacao": "Não guardado",
                        "tem_arquivo": false,
                        "arquivo_url": null
                    }
                ]
            },
            "pops": {
                "situacao": {
                    "total": 19,
                    "aprovados": 19,
                    "rascunhos": 0,
                    "em_revisao": 0,
                    "vencidos": 0,
                    "perto": 0
                },
                "resumo": {
                    "ok": 18,
                    "fazer": 0,
                    "atrasado": 0
                },
                "em_dia": [
                    {
                        "grupo": "Documentos",
                        "titulo": "Licença sanitária",
                        "base": "RDC 1.002/2025",
                        "estado": "ok",
                        "detalhe": "Vale até 22/07/2027"
                    },
                    {
                        "grupo": "Esterilização",
                        "titulo": "Teste biológico da autoclave",
                        "base": "RDC 1.002/2025",
                        "estado": "ok",
                        "detalhe": "Último teste há 2 dias"
                    },
                    {
                        "grupo": "Rotina",
                        "titulo": "Limpeza da caixa d’água",
                        "base": "RDC 1.002/2025",
                        "estado": "ok",
                        "detalhe": "Feita há 2 meses"
                    }
                ],
                "pops": [
                    {
                        "codigo": "POP-01",
                        "titulo": "Higienização das mãos",
                        "versao": 2,
                        "aprovado_em": "2026-06-22",
                        "revisar_ate": "2027-06-22",
                        "situacao": "Aprovado"
                    },
                    {
                        "codigo": "POP-07",
                        "titulo": "Processamento de artigos e esterilização",
                        "versao": 3,
                        "aprovado_em": "2026-09-22",
                        "revisar_ate": "2027-09-22",
                        "situacao": "Aprovado"
                    },
                    {
                        "codigo": "POP-15",
                        "titulo": "Plano de Gerenciamento de Resíduos (PGRSS)",
                        "versao": 2,
                        "aprovado_em": "2026-08-22",
                        "revisar_ate": "2027-08-22",
                        "situacao": "Aprovado"
                    }
                ]
            },
            "autoclave": {
                "ciclos_30_dias": 41,
                "testes": [
                    {
                        "data": "2026-11-20T08:15:00-03:00",
                        "equipamento": "Autoclave de exemplo",
                        "numero": "128",
                        "biologico": "Aprovado",
                        "bowie_dick": null
                    },
                    {
                        "data": "2026-11-13T08:05:00-03:00",
                        "equipamento": "Autoclave de exemplo",
                        "numero": "121",
                        "biologico": "Aprovado",
                        "bowie_dick": "Aprovado"
                    }
                ]
            },
            "pgrss": {
                "plano": {
                    "codigo": "POP-15",
                    "titulo": "Plano de Gerenciamento de Resíduos (PGRSS)",
                    "versao": 2,
                    "aprovado_em": "2026-08-22",
                    "situacao": "Aprovado"
                },
                "contrato": {
                    "numero": "CT-01/2026",
                    "vence_em": "2027-09-22",
                    "situacao": "Em dia"
                },
                "ultima_coleta": "2026-11-16",
                "coletas_12_meses": 24
            },
            "pasta": {
                "id": 9000010,
                "gerada_em": "2026-11-19T14:00:00-03:00",
                "de": "2025-11-22",
                "ate": "2026-11-19",
                "zip_url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta",
                "itens": [
                    {
                        "n": 0,
                        "parte": "Manual de POPs",
                        "titulo": "Manual de POPs",
                        "detalhe": "19 POPs aprovados",
                        "arquivo": "manual-de-pops.pdf",
                        "url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta/0"
                    },
                    {
                        "n": 2,
                        "parte": "Autoclave",
                        "titulo": "Testes da autoclave",
                        "detalhe": "12 meses",
                        "arquivo": "testes-da-autoclave.pdf",
                        "url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta/2"
                    },
                    {
                        "n": 5,
                        "parte": "Pasta da vigilância",
                        "titulo": "Lista dos documentos",
                        "detalhe": null,
                        "arquivo": "lista-dos-documentos.pdf",
                        "url": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta/5"
                    }
                ]
            }
        },
        "links": {
            "ficha": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001",
            "pops": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pops",
            "pasta": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta"
        }
    }
}

Erros possíveis: 401, 403, 429, 503, 404. Veja Erros.

GET /clinicas/{clinica}/pops

Situação dos POPs

Os POPs da RDC 1.002/2025 e o "Em dia com a Anvisa". Precisa do bloco "pops" liberado.

ParâmetroOndeO que é
clinica* caminho id da clínica (o campo id da lista).

Requisição

curl -H "Authorization: Bearer tdv_teste_clinicas_de_exemplo" "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pops"

Resposta 200

{
    "data": {
        "clinica_id": 900002,
        "situacao": "atencao",
        "atualizado_em": "2026-11-17T16:10:00-03:00",
        "resumo": {
            "ok": 15,
            "fazer": 2,
            "atrasado": 0
        },
        "em_dia": [
            {
                "grupo": "Documentos",
                "titulo": "Licença sanitária",
                "base": "RDC 1.002/2025",
                "estado": "fazer",
                "detalhe": "Vale até 12/12/2026"
            },
            {
                "grupo": "Esterilização",
                "titulo": "Teste biológico da autoclave",
                "base": "RDC 1.002/2025",
                "estado": "ok",
                "detalhe": "Último teste há 2 dias"
            },
            {
                "grupo": "Rotina",
                "titulo": "Limpeza da caixa d’água",
                "base": "RDC 1.002/2025",
                "estado": "fazer",
                "detalhe": "Vence em 10 dias"
            }
        ],
        "pops": [
            {
                "codigo": "POP-01",
                "titulo": "Higienização das mãos",
                "versao": 2,
                "aprovado_em": "2026-06-22",
                "revisar_ate": "2027-06-22",
                "situacao": "Aprovado"
            },
            {
                "codigo": "POP-07",
                "titulo": "Processamento de artigos e esterilização",
                "versao": 3,
                "aprovado_em": "2026-09-22",
                "revisar_ate": "2027-09-22",
                "situacao": "Aprovado"
            },
            {
                "codigo": "POP-15",
                "titulo": "Plano de Gerenciamento de Resíduos (PGRSS)",
                "versao": 2,
                "aprovado_em": "2026-08-22",
                "revisar_ate": "2027-08-22",
                "situacao": "Aprovado"
            }
        ]
    }
}

Erros possíveis: 401, 403, 429, 503, 404. Veja Erros.

GET /clinicas/{clinica}/pasta

Baixar a Pasta do fiscal (.zip)

O último arquivo da Pasta do fiscal gerado pela clínica, só com as partes que podem sair (sem fichas da equipe nem eventos adversos). Precisa do bloco "pasta".

ParâmetroOndeO que é
clinica* caminho id da clínica (o campo id da lista).

Requisição

curl -OJ -H "Authorization: Bearer tdv_teste_clinicas_de_exemplo" "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta"

Resposta 200

O próprio arquivo (application/zip), com o nome no cabeçalho Content-Disposition.

Erros possíveis: 401, 403, 429, 503, 404. Veja Erros.

GET /clinicas/{clinica}/pasta/{n}

Baixar um arquivo da Pasta do fiscal

Um item da pasta pelo campo n de blocos.pasta.itens. Precisa do bloco "pasta".

ParâmetroOndeO que é
clinica* caminho id da clínica (o campo id da lista).
n* caminho O campo n do item.

Requisição

curl -OJ -H "Authorization: Bearer tdv_teste_clinicas_de_exemplo" "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta/0"

Resposta 200

O próprio arquivo (application/pdf), com o nome no cabeçalho Content-Disposition.

Erros possíveis: 401, 403, 429, 503, 404. Veja Erros.

GET /clinicas/{clinica}/documentos/{documento}

Baixar um documento da pasta da vigilância

Licença, alvará e outros documentos de blocos.licencas.documentos com tem_arquivo = true. Documentos com dado pessoal ou de saúde da equipe nunca saem. Precisa do bloco "licencas".

ParâmetroOndeO que é
clinica* caminho id da clínica (o campo id da lista).
documento* caminho O campo documento_id.

Requisição

curl -OJ -H "Authorization: Bearer tdv_teste_clinicas_de_exemplo" "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/documentos/9000011"

Resposta 200

O próprio arquivo (application/pdf), com o nome no cabeçalho Content-Disposition.

Erros possíveis: 401, 403, 429, 503, 404. Veja Erros.

O que cada bloco traz

A ficha é dividida em blocos, e cada clínica escolhe quais mostrar. O campo blocos_liberados diz quais vieram; bloco não liberado simplesmente não aparece em blocos.

BlocoO que traz
dadosDados da clínicaNome, CNPJ, CNES, endereço, telefone e e-mail.
responsavelResponsável técnicoNome e CRO do responsável técnico e do substituto.
licencasLicença, alvará e documentosLicença sanitária, alvará e os documentos da pasta da vigilância, com a validade.
popsManual de POPsOs documentos da RDC 1.002/2025 e a situação “Em dia com a Anvisa”.
autoclaveTestes da autoclaveOs últimos testes biológicos e de Bowie & Dick.
pgrssResíduos (PGRSS)O plano de resíduos, o contrato de coleta e a última coleta.
pastaPasta do fiscalO último arquivo gerado na Pasta do fiscal, para baixar.

Situação da clínica

O campo situacao resume o “Em dia com a Anvisa” (itens da RDC 1.002/2025) e serve de filtro em /clinicas?situacao=:

  • em_dia — Tudo em dia com a RDC 1.002/2025.
  • atencao — Nada atrasado, mas há itens na hora de fazer.
  • atrasada — Há itens atrasados ou sem registro.
  • sem_informacao — A clínica não liberou o bloco de POPs.

Datas sem hora vêm como AAAA-MM-DD; com hora, em ISO 8601 com fuso (2026-11-22T10:20:00-03:00).

Exemplos de código

Os exemplos usam a chave de teste. Para usar com a vigilância de verdade, troque pela chave que ela gerou.

# Quem é a chave (bom para testar a ligação)
curl -H "Authorization: Bearer tdv_teste_clinicas_de_exemplo" https://app.temdentista.com.br/api/v1/vigilancia/eu

# Clínicas com mudança na ficha desde 1º de novembro, 100 por página
curl -H "Authorization: Bearer tdv_teste_clinicas_de_exemplo" "https://app.temdentista.com.br/api/v1/vigilancia/clinicas?atualizado_desde=2026-11-01&por_pagina=100"

# Ficha de uma clínica
curl -H "Authorization: Bearer tdv_teste_clinicas_de_exemplo" https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001

# Pasta do fiscal (.zip)
curl -H "Authorization: Bearer tdv_teste_clinicas_de_exemplo" -o pasta.zip https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001/pasta
<?php
$api = 'https://app.temdentista.com.br/api/v1/vigilancia';
$chave = getenv('TEMDENTISTA_CHAVE') ?: 'tdv_teste_clinicas_de_exemplo';

function pedir(string $url, string $chave): array
{
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer '.$chave, 'Accept: application/json'],
        CURLOPT_TIMEOUT => 30,
    ]);
    $corpo = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    $json = json_decode($corpo, true);
    if ($status !== 200) {
        throw new RuntimeException($json['erro']['codigo'].': '.$json['erro']['mensagem']);
    }

    return $json;
}

// Todas as clínicas, página por página, e a ficha de cada uma
$url = $api.'/clinicas?por_pagina=100';
while ($url) {
    $pagina = pedir($url, $chave);
    foreach ($pagina['data'] as $clinica) {
        $ficha = pedir($clinica['links']['ficha'], $chave)['data'];
        echo $ficha['nome'].' - '.$ficha['situacao'].PHP_EOL;
    }
    $url = $pagina['links']['proxima'];
}
import os, time, requests

API = "https://app.temdentista.com.br/api/v1/vigilancia"
CHAVE = os.environ.get("TEMDENTISTA_CHAVE", "tdv_teste_clinicas_de_exemplo")
sessao = requests.Session()
sessao.headers["Authorization"] = f"Bearer {CHAVE}"

def pedir(url, **params):
    while True:
        r = sessao.get(url, params=params, timeout=30)
        if r.status_code == 429:  # passou do limite por minuto: espera e tenta de novo
            time.sleep(int(r.headers.get("Retry-After", "60")))
            continue
        if r.status_code != 200:
            erro = r.json()["erro"]
            raise RuntimeError(f'{erro["codigo"]}: {erro["mensagem"]}')
        return r.json()

url, params = f"{API}/clinicas", {"por_pagina": 100, "atualizado_desde": "2026-11-01"}
while url:
    pagina = pedir(url, **params)
    for clinica in pagina["data"]:
        ficha = pedir(clinica["links"]["ficha"])["data"]
        print(ficha["nome"], ficha["situacao"], ficha["blocos_liberados"])
    url, params = pagina["links"]["proxima"], {}
// Node 18 ou mais novo (fetch já vem junto)
const API = "https://app.temdentista.com.br/api/v1/vigilancia";
const CHAVE = process.env.TEMDENTISTA_CHAVE ?? "tdv_teste_clinicas_de_exemplo";

async function pedir(url) {
  const r = await fetch(url, { headers: { Authorization: `Bearer ${CHAVE}` } });
  if (r.status === 429) {
    const segundos = Number(r.headers.get("Retry-After") ?? 60);
    await new Promise((pronto) => setTimeout(pronto, segundos * 1000));
    return pedir(url);
  }
  const json = await r.json();
  if (!r.ok) throw new Error(`${json.erro.codigo}: ${json.erro.mensagem}`);
  return json;
}

let url = `${API}/clinicas?por_pagina=100&situacao=atrasada`;
while (url) {
  const pagina = await pedir(url);
  for (const clinica of pagina.data) {
    console.log(clinica.nome, clinica.situacao, clinica.em_dia);
  }
  url = pagina.links.proxima;
}

Para sincronizar uma base local: na primeira vez, percorra /clinicas inteira; depois, uma vez por dia (ou ao receber um aviso), peça só atualizado_desde a data da última sincronização. Como clínica que desliga o compartilhamento some da lista, apague da sua base quem não aparece mais na lista completa (ou use o aviso compartilhamento.desligado).

Avisos (webhooks)

Opcional. Se o sistema quiser ser avisado em vez de perguntar de tempos em tempos, passe à vigilância um endereço https://. Ela cadastra o endereço junto com a chave e recebe um segredo (começa com whsec_) para passar ao sistema. O aviso diz só qual clínica mudou; os dados o sistema busca pela API.

  • compartilhamento.ligado — Uma clínica da área ligou o compartilhamento com a vigilância (passa a aparecer na API).
  • compartilhamento.desligado — Uma clínica desligou o compartilhamento: apague a cópia local da ficha dela.
  • ficha.atualizada — Algo mudou na ficha de uma clínica (blocos liberados, POPs, documentos, testes, resíduos ou Pasta do fiscal).

Chega como POST com o corpo abaixo e os cabeçalhos X-TemDentista-Evento, X-TemDentista-Envio e X-TemDentista-Assinatura: t=<unix>,v1=<hmac>, onde o hmac é o HMAC-SHA256 de "t.corpo" com o segredo. Responda qualquer 2xx em até 10 segundos; sem isso, tentamos de novo até 6 vezes (1 min, 5 min, 30 min, 2 h e 6 h). O id se repete nas novas tentativas: use para não processar duas vezes. O aviso ficha.atualizada sai até uma hora depois da mudança.

{
    "id": 1532,
    "evento": "ficha.atualizada",
    "criado_em": "2026-11-22T10:20:00-03:00",
    "clinica_id": 900001,
    "links": {
        "ficha": "https://app.temdentista.com.br/api/v1/vigilancia/clinicas/900001"
    }
}

Conferir a assinatura

<?php
$corpo = file_get_contents('php://input');            // o corpo cru, antes de decodificar
$cabecalho = $_SERVER['HTTP_X_TEMDENTISTA_ASSINATURA'] ?? '';
parse_str(str_replace(',', '&', $cabecalho), $partes); // t=…&v1=…
$esperado = hash_hmac('sha256', ($partes['t'] ?? '').'.'.$corpo, getenv('TEMDENTISTA_SEGREDO'));
if (! hash_equals($esperado, $partes['v1'] ?? '') || abs(time() - (int) ($partes['t'] ?? 0)) > 300) {
    http_response_code(401);
    exit;
}
$aviso = json_decode($corpo, true);
// $aviso['evento']: compartilhamento.ligado | compartilhamento.desligado | ficha.atualizada
http_response_code(200);
import hmac, hashlib, time

def aviso_valido(corpo: bytes, cabecalho: str, segredo: str) -> bool:
    partes = dict(p.split("=", 1) for p in cabecalho.split(",") if "=" in p)
    mensagem = partes.get("t", "").encode() + b"." + corpo
    esperado = hmac.new(segredo.encode(), mensagem, hashlib.sha256).hexdigest()
    recente = abs(time.time() - int(partes.get("t", "0"))) <= 300
    return recente and hmac.compare_digest(esperado, partes.get("v1", ""))
import crypto from "node:crypto";

// corpo: o texto cru recebido (não o objeto já convertido)
function avisoValido(corpo, cabecalho, segredo) {
  const partes = Object.fromEntries(cabecalho.split(",").map((p) => p.split("=")));
  const esperado = crypto.createHmac("sha256", segredo).update(`${partes.t}.${corpo}`).digest("hex");
  const recebido = partes.v1 ?? "";
  const igual = recebido.length === esperado.length
    && crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(recebido));
  return igual && Math.abs(Date.now() / 1000 - Number(partes.t)) <= 300;
}

Erros

Todo erro vem no mesmo formato, com um codigo fixo para o sistema tratar e uma mensagem em português para mostrar a uma pessoa:

{
    "erro": {
        "codigo": "chave_revogada",
        "mensagem": "Esta chave foi revogada em 20/11/2026. Peça uma nova à vigilância sanitária.",
        "documentacao": "https://desenvolvedor.temdentista.com.br#erros"
    }
}
HTTPcodigoQuando
401chave_ausenteNão veio a chave no cabeçalho Authorization (ou X-Api-Key).
401chave_invalidaA chave não existe. Confira se foi copiada inteira, com o tdv_ do começo.
401chave_revogadaA vigilância revogou a chave. Peça uma nova a ela.
403orgao_desligadoO órgão dono da chave está desligado no Tem Dentista.
422parametro_invalidoAlgum parâmetro da URL está fora do formato (a mensagem diz qual).
404clinica_nao_encontradaA clínica não existe, fica fora da área do órgão ou desligou o compartilhamento (de propósito, a resposta é a mesma nos três casos).
404bloco_nao_liberadoA clínica não liberou o bloco que a rota precisa (pops, pasta ou licencas).
404pasta_inexistenteA clínica liberou a Pasta do fiscal, mas ainda não gerou nenhuma.
404arquivo_nao_encontradoO item da pasta ou o documento não existe, não tem arquivo ou tem dado pessoal da equipe (esses nunca saem).
404rota_inexistenteO endereço não existe na API.
405metodo_nao_permitidoA API é só de leitura: use GET.
429limite_excedidoPassou do limite de requisições por minuto. Espere os segundos do cabeçalho Retry-After.
503api_desligadaA API está desligada no momento (manutenção). Tente mais tarde.
500erro_internoFalha do nosso lado. Já somos avisados; tente de novo em alguns minutos.

Limites

Até 60 requisições por minuto por chave (a chave de teste conta por endereço IP). Cada resposta traz X-RateLimit-Limit e X-RateLimit-Remaining. Passou do limite: erro 429 limite_excedido com o cabeçalho Retry-After (segundos até poder tentar de novo).

Até 100 clínicas por página. Para manter uma base atualizada, prefira atualizado_desde ou os avisos a percorrer tudo várias vezes por dia.

Versionamento

A versão principal está no endereço (/api/v1). Toda resposta traz o cabeçalho X-Api-Versao (agora 1.0.0). Dentro da v1 nada é tirado nem muda de sentido: só podem aparecer campos, rotas e eventos novos, então o sistema deve ignorar campos que não conhece. Mudança que quebra compatibilidade vira /api/v2, com a v1 funcionando em paralelo por pelo menos 12 meses e aviso neste portal.

Privacidade e LGPD

  • Nunca sai dado de paciente. Também não saem fichas de saúde da equipe, comprovantes de vacinação nem eventos adversos.
  • Só aparecem as clínicas que ligaram o compartilhamento com a vigilância, e só os blocos que cada uma escolheu.
  • Cada consulta pela API fica registrada e aparece para a clínica, com o nome do sistema e do órgão.
  • Quando a clínica desliga o compartilhamento, o acesso acaba na hora. O sistema deve apagar a cópia local da ficha dela.

Histórico de versões

  • 1.0.0 · 2026-11-22 Primeira versão: lista de clínicas com filtros, ficha, situação dos POPs, Pasta do fiscal e arquivos, avisos por webhook e ambiente de testes.

Arquivo OpenAPI

A descrição completa da API em OpenAPI 3.1, para gerar cliente, importar no Postman/Insomnia ou validar respostas. É gerada do mesmo código da API e conferida nos testes automáticos a cada mudança.

Baixar openapi.json