Versão 1 · Version 1
Português
Com esta API, o sistema do seu cliente (portal, intranet, painel) lista as peças que a Typemedia mandou para aprovação, mostra os arquivos e registra a decisão: aprovar ou pedir ajuste. O cliente aprova no sistema dele, sem criar conta aqui.
Cada chave pertence a um cliente de uma conta. Ela só enxerga as peças desse cliente.
Autenticação
Envie a chave no cabeçalho Authorization. Quem cria a chave é o titular, sócio ou administrador da conta, em Conta → Integrações de parceiros. A chave aparece uma única vez, no formato tmp_<8 caracteres>_<64 caracteres>. Guarde-a no servidor, nunca em código que o navegador baixa. A chave com o escopo `aprovacoes:decidir` só vale de servidor para servidor: uma chamada do navegador (com cabeçalho Origin) com ela é recusada com 403 chave_so_servidor. Para o navegador, use uma chave só de leitura.
Authorization: Bearer tmp_1a2b3c4d_...Endereço base: https://typemedia.com.br/api/parceiros/v1
Escopos da chave:
| Escopo | Permite |
|---|---|
aprovacoes:ler | Listar peças e ver cada peça |
aprovacoes:decidir | Aprovar ou pedir ajuste |
Listar peças
GET /pecas?estado=em_aprovacao&limite=50&deslocamento=0
O estado é opcional: em_aprovacao, ajuste_pedido, aprovada, agendada ou publicada. Rascunhos e peças arquivadas nunca aparecem. limite vai até 100.
curl -H "Authorization: Bearer $CHAVE" \
"https://typemedia.com.br/api/parceiros/v1/pecas?estado=em_aprovacao"{
"total": 1, "limite": 50, "deslocamento": 0,
"dados": [
{ "id": "6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11", "titulo": "Post de abertura", "formato": "post", "canal": "instagram",
"estado": "em_aprovacao", "data_prevista": "2026-12-01", "versao_atual": 2, "atualizada_em": "2026-11-09T12:00:00+00:00" }
]
}Ver uma peça
GET /pecas/{id}
Traz as versões, a mensagem que a equipe escreveu para o cliente (mensagem), os comentários visíveis ao cliente e os arquivos. Cada arquivo tem uma url assinada que vale por 5 minutos: busque de novo a peça para ter uma URL nova. Notas internas da equipe nunca saem pela API. Peça de outro cliente responde 404, igual a peça que não existe.
curl -H "Authorization: Bearer $CHAVE" \
https://typemedia.com.br/api/parceiros/v1/pecas/6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11{
"id": "6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11", "titulo": "Post de abertura", "estado": "em_aprovacao", "legenda": "Texto da legenda", "versao_atual": 2,
"versoes": [
{ "numero": 2, "mensagem": "Ajustamos a cor do título.", "criada_em": "2026-11-09T12:00:00+00:00",
"arquivos": [ { "nome": "post.png", "mime": "image/png", "tamanho": 183204, "url": "https://...", "url_expira_em": "2026-11-09T12:05:00.000Z" } ] }
],
"comentarios": []
}Decidir
POST /pecas/{id}/decisao
| Campo | Regra |
|---|---|
decisao | aprovar ou ajuste |
nome | Obrigatório, até 120 caracteres: quem decidiu, no sistema do cliente |
comentario | Opcional ao aprovar; obrigatório ao pedir ajuste (até 5000 caracteres) |
Só vale para peça em em_aprovacao. A decisão fica registrada com o nome informado e a chave usada.
curl -X POST -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
-d '{"decisao":"ajuste","nome":"Maria da Silva","comentario":"Trocar a foto"}' \
https://typemedia.com.br/api/parceiros/v1/pecas/6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11/decisao{ "id": "6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11", "estado": "ajuste_pedido", "versao": 2 }Webhook
Se a chave tiver um endereço de webhook, enviamos um POST com corpo JSON quando uma peça do cliente entra em aprovação (peca.em_aprovacao) ou ganha versão nova enquanto já está em aprovação (peca.versao_nova). Uma versão nova numa peça que estava em ajuste ou aprovada devolve a peça à aprovação e gera um único evento peca.em_aprovacao.
{
"id": "e2b0f7a4-4c1d-4e0f-a3b7-0d9a1b6f5c22", "evento": "peca.em_aprovacao", "ocorrido_em": "2026-11-09T12:00:00+00:00", "chave_prefixo": "1a2b3c4d",
"peca": { "id": "6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11", "titulo": "Post de abertura", "formato": "post", "canal": "instagram", "estado": "em_aprovacao", "versao_atual": 2 }
}O aviso só diz que algo mudou: busque a peça pela API para ver o conteúdo. Cabeçalhos enviados:
| Cabeçalho | Valor |
|---|---|
X-Typemedia-Assinatura | sha256=<HMAC-SHA256 hexadecimal do corpo, com o segredo do webhook> |
X-Typemedia-Evento | O evento |
X-Typemedia-Entrega | O id da entrega, igual ao id do corpo: use para ignorar repetições |
Como validar a assinatura (Node.js): calcule o HMAC do corpo exatamente como chegou (antes de converter para objeto) e compare em tempo constante.
import { createHmac, timingSafeEqual } from 'node:crypto';
function assinaturaValida(corpoBruto, cabecalho, segredo) {
const esperado = 'sha256=' + createHmac('sha256', segredo).update(corpoBruto).digest('hex');
const a = Buffer.from(esperado), b = Buffer.from(cabecalho ?? '');
return a.length === b.length && timingSafeEqual(a, b);
}Compare também ocorrido_em com o relógio do seu servidor e recuse avisos muito antigos. Responda com status 2xx em até 5 segundos. Se falhar, tentamos até 3 vezes (agora, depois de 2 s e depois de 8 s); depois a entrega fica como "Falhou" e pode ser reenviada na tela de Integrações de parceiros. O endereço precisa ser https://, na porta 443, e público (conectamos no IP que conferimos); redirecionamentos não são seguidos. Use id para tratar repetições.
Limites e CORS
- 120 chamadas por minuto por chave. Acima disso:
429com o cabeçalhoRetry-After(segundos). Cada resposta trazX-RateLimit-LimiteX-RateLimit-Remaining. - Chamadas de servidor não precisam de CORS. Para chamar do navegador, cadastre o site da chave (por exemplo
https://portal.exemplo.com.br); só essas origens recebemAccess-Control-Allow-Origin. Não existe*. Do navegador só funcionam chaves de leitura: a chave comaprovacoes:decidiré recusada (chave_so_servidor) e a decisão deve ser enviada pelo seu servidor. Prefira sempre chamar do seu servidor, para não expor a chave. - Tentativas com chave inválida são limitadas por endereço IP (60 por minuto): acima disso,
429.
Erros
Todo erro vem como { "erro": { "codigo": "...", "mensagem": "..." } }.
| Status | Código | Quando |
|---|---|---|
| 400 | estado_invalido, parametros_invalidos, json_invalido, decisao_invalida | Pedido mal formado |
| 401 | nao_autorizado, chave_invalida, chave_revogada, chave_inativa | Chave ausente, errada, revogada ou sem cliente ativo |
| 403 | sem_escopo, origem_nao_permitida, chave_so_servidor | Chave sem o escopo, origem não cadastrada, ou chave que decide usada do navegador |
| 404 | peca_nao_encontrada | Peça inexistente ou de outro cliente |
| 409 | peca_nao_esta_em_aprovacao | A peça não está esperando decisão |
| 422 | nome_obrigatorio, comentario_obrigatorio, comentario_longo | Dados da decisão |
| 429 | limite_excedido | Passou do limite por minuto |
| 500 | falha_interna | Tente de novo |
Rede, v1 (contrato, sem implementação)
> Estado: contrato, não serviço. Nada desta seção responde ainda: os caminhos abaixo existem só para o domínio de quem contrata (organização, governo, negócio com propósito) poder ser construído sobre eles. Hoje devolvem 404. A implementação começa quando esse domínio for aberto; até lá, o contrato só muda de forma compatível e a mudança entra aqui antes de entrar no código.
Estende esta API para as oportunidades, candidaturas, contratos, marcos e avaliações da rede. Quem usa o quê: quem publica e contrata publica a oportunidade, escolhe quem candidatou, aprova a entrega, registra o pagamento e avalia; quem presta o serviço candidata, entrega e avalia. As regras (quem pode, em que estado, qual limite do plano) ficam no banco e são as mesmas das telas: a API não tem regra própria.
Autenticação e chave. Mesmo cabeçalho Authorization: Bearer tmp_... e mesmo formato de chave. A diferença: a chave da rede é presa a uma conta (não a um cliente) e age em nome dela. O que a conta não pode fazer na tela (conta sem verificação, vínculo pendente, limite do plano) a chave também não pode. Mesma gestão, na tela Conta → Integrações de parceiros; mesmo limite_por_minuto, mesmas origens e mesma regra de CORS.
| Escopo | Permite |
|---|---|
rede:ler | Listar e ver oportunidades, candidaturas, contratos, marcos e avaliações da conta |
rede:escrever | Publicar, candidatar, escolher, responder contrato, entregar, decidir entrega, registrar pagamento e avaliar |
Nome antigo. Estes escopos se chamavam marketplace:ler e marketplace:escrever. O nome antigo continua aceito por enquanto, como equivalente do novo: chave que já o tem segue valendo, e a criação de chave nova oferece só rede:ler e rede:escrever.
Como na decisão de peças, uma chave com rede:escrever só vale de servidor para servidor: com Origin ou Sec-Fetch-Site é recusada com 403 chave_so_servidor. Um mesmo pedido nunca troca de conta: o id de um recurso de outra conta responde 404, igual ao que não existe.
Paginação, formatos e repetição. Toda lista aceita limite (até 100) e deslocamento e responde { "total", "limite", "deslocamento", "dados": [...] }. Datas em ISO 8601, valores em reais como número com duas casas. Todo POST aceita o cabeçalho Idempotency-Key (texto de até 64 caracteres): repetir a mesma chave devolve a primeira resposta sem refazer a ação.
| Recurso | Método e caminho | Escopo | Quem usa | O que faz |
|---|---|---|---|---|
| Oportunidades | GET /oportunidades | ler | todos | Oportunidades abertas, só campos públicos. A lista segue o plano da conta da chave (nível e atraso de exibição), como na tela |
GET /oportunidades/{id} | ler | todos | Uma oportunidade aberta ou da própria conta | |
POST /oportunidades | escrever | quem publica | Publica oportunidade | |
POST /oportunidades/{id}/fechamento | escrever | quem publica | Fecha a oportunidade (fechada) | |
| Candidaturas | GET /oportunidades/{id}/candidaturas | ler | quem publica | Candidaturas recebidas da própria oportunidade |
POST /oportunidades/{id}/candidaturas | escrever | quem presta | Candidata a conta da chave | |
GET /candidaturas | ler | todos | Candidaturas enviadas ou recebidas pela conta | |
POST /candidaturas/{id}/escolha | escrever | quem publica | Escolhe a candidatura e cria o contrato com os marcos | |
| Contratos | GET /contratos | ler | todos | Contratos em que a conta é parte; filtro estado |
GET /contratos/{id} | ler | todos | Contrato com marcos e histórico | |
POST /contratos/{id}/resposta | escrever | a parte que ainda não respondeu | Aceita ou recusa o contrato | |
| Marcos | GET /contratos/{id}/marcos | ler | todos | Marcos e a entrega mais recente de cada um |
POST /marcos/{id}/arquivos | escrever | quem presta | Reserva envio de arquivo da entrega (URL assinada de envio) | |
POST /marcos/{id}/entrega | escrever | quem presta | Entrega o marco | |
POST /entregas/{id}/decisao | escrever | quem contrata | Aprova ou pede ajuste | |
POST /marcos/{id}/pagamento | escrever | quem contrata | Registra o pagamento do marco aprovado | |
| Avaliações | GET /contratos/{id}/avaliacoes | ler | todos | Avaliações visíveis para a conta (regra às cegas) |
POST /contratos/{id}/avaliacoes | escrever | todos | Avalia o contrato num momento | |
| Diretório | GET /diretorio?cnpj=<14 dígitos> | ler | todos | Uma organização por CNPJ exato, só campos públicos. Só existe no diretório quem criou conta, reivindicou o perfil e está ativo: qualquer outro CNPJ responde 404 |
| Acompanhamentos | GET /acompanhamentos | ler | quem presta | Trabalhos fechados da conta da chave, com o estado de cada um; filtro estado |
GET /acompanhamentos/{id} | ler | quem presta | Um trabalho com os marcos e o estado de cada um; sem dados do cliente além do nome |
Oportunidades
Os campos são os mesmos que a tela mostra a quem lê o feed; conta_id e dados internos não saem.
curl -H "Authorization: Bearer $CHAVE" \
"https://typemedia.com.br/api/parceiros/v1/oportunidades?limite=20"{
"total": 1, "limite": 20, "deslocamento": 0,
"dados": [
{ "id": "b3a1d0f2-5c47-4e8a-9a1e-7c2d4f6b8e10", "conta_nome": "Instituto Exemplo", "titulo": "Identidade visual para festival",
"descricao": "Logotipo, paleta e aplicações básicas.", "area": "design", "nivel": "aberta",
"valor_estimado": 8000.00, "prazo": "2026-12-20", "modalidade": "remoto", "local": null,
"projeto_nome": "Festival Exemplo 2027", "criado_em": "2026-11-10T14:00:00+00:00" }
]
}nivel é aberta ou verba_aprovada. Publicar:
POST /oportunidades com titulo (até 200 caracteres), descricao (até 5000), area, valor_estimado, prazo, modalidade (remoto, presencial ou hibrido), local, projeto_id (projeto público da própria conta) e nivel. Responde 201 com a oportunidade.
{ "titulo": "Identidade visual para festival", "descricao": "Logotipo, paleta e aplicações básicas.", "area": "design",
"valor_estimado": 8000.00, "prazo": "2026-12-20", "modalidade": "remoto", "nivel": "aberta" }Candidaturas e escolha
POST /oportunidades/{id}/candidaturas com mensagem (até 3000 caracteres), valor_proposto e portfolio_url. Responde 201 com { "id", "estado": "enviada" }. O estado de uma candidatura é enviada, escolhida, recusada ou retirada. Cada conta se candidata uma vez por oportunidade (409 candidatura_repetida).
POST /candidaturas/{id}/escolha com o escopo e a lista de marcos (cada um com titulo, valor e data_prevista). Cria o contrato, que nasce proposto, e recusa as demais candidaturas da oportunidade.
{ "escopo": "Logotipo, paleta e aplicações básicas, em duas rodadas de ajuste.",
"marcos": [ { "titulo": "Conceito aprovado", "valor": 3000.00, "data_prevista": "2026-12-01" },
{ "titulo": "Arquivos finais", "valor": 5000.00, "data_prevista": "2026-12-20" } ] }Contratos
Estados: proposto (espera a resposta de quem presta), aguardando_contratante (nasce de proposta comercial; só a contratante responde), ativo, concluido, cancelado e recusado. Contrato é permissão financeira: a conta precisa estar verificada, senão 403 conta_nao_verificada.
{
"id": "0d9e7c44-2f1b-4a60-8b35-91c3a5e7d2f8", "titulo": "Identidade visual para festival", "estado": "proposto",
"contratante_nome": "Instituto Exemplo", "profissional_nome": "Ana Exemplo", "valor_total": 8000.00,
"oportunidade_id": "b3a1d0f2-5c47-4e8a-9a1e-7c2d4f6b8e10", "criado_em": "2026-11-10T15:00:00+00:00",
"marcos": [ { "id": "e1f2a3b4-0000-4c11-9d22-aaaabbbbcccc", "titulo": "Conceito aprovado", "valor": 3000.00, "estado": "a_fazer", "data_prevista": "2026-12-01", "pago_em": null } ],
"historico": [ { "texto": "Contrato proposto", "autor_nome": "Instituto Exemplo", "criado_em": "2026-11-10T15:00:00+00:00" } ]
}POST /contratos/{id}/resposta com { "decisao": "aceitar" } ou { "decisao": "recusar", "motivo": "..." }. A API escolhe a regra certa pela posição da conta no contrato. A taxa que a plataforma cobra não faz parte do contrato da API: ela é regra da plataforma, definida no banco no momento da escolha, e não aparece nem se altera por aqui.
Marcos, entregas e pagamento
Estados do marco: a_fazer, entregue, aprovado, pago. O contrato vira concluido quando o último marco é pago.
POST /marcos/{id}/arquivoscom{ "nome", "mime", "tamanho" }devolve{ "caminho", "url_envio", "url_envio_expira_em" }: envie o arquivo comPUTnaurl_envio(vale 5 minutos) e use ocaminhona entrega.POST /marcos/{id}/entregacom{ "nota": "...", "arquivos": [ { "caminho": "..." } ] }. Só marcoa_fazerde contratoativo. Responde201com{ "entrega_id" }.POST /entregas/{id}/decisaocom{ "decisao": "aprovada" | "ajuste", "comentario": "..." }; o comentário é obrigatório no ajuste.POST /marcos/{id}/pagamentoregistra que o pagamento foi feito fora da plataforma. A API não movimenta dinheiro. Só marcoaprovado.
Avaliações
POST /contratos/{id}/avaliacoes com momento (fechamento ou entrega), nps (0 a 10), nota_contraparte (1 a 5) e porque. Uma por conta, contrato e momento (409 avaliacao_repetida).
Visibilidade às cegas. O GET devolve sempre a avaliação da própria conta. A nota_contraparte e o porque da outra parte só aparecem quando as duas contas responderam ao mesmo momento ou 14 dias depois da primeira resposta (liberada_em). Antes disso o campo vem null. O nps da plataforma nunca é mostrado à contraparte.
{ "dados": [
{ "momento": "fechamento", "de": "propria", "nps": 9, "nota_contraparte": 5, "porque": "Briefing claro.", "criada_em": "2026-11-12T10:00:00+00:00", "liberada_em": null },
{ "momento": "fechamento", "de": "contraparte", "nota_contraparte": null, "porque": null, "criada_em": "2026-11-12T11:00:00+00:00", "liberada_em": null }
] }Diretório e acompanhamentos
Contrato, ainda sem implementação, como o resto desta seção. Os dois recursos seguem a regra da rede: o diretório só tem quem criou conta, reivindicou o perfil e está ativo. Uma organização que nunca criou conta não existe para a API, mesmo que o CNPJ dela seja conhecido por outra origem.
GET /diretorio?cnpj=<14 dígitos> (escopo rede:ler). Devolve uma entidade pelo CNPJ exato, só com campos públicos. Não há lista, não há busca por nome e não há exportação: sem o parâmetro cnpj, ou com um CNPJ de organização que não está na rede, a resposta é 404 entidade_nao_encontrada; CNPJ malformado dá 422 cnpj_invalido.
{ "cnpj": "11222333000181", "tipo": "organizacao", "nome": "Instituto Exemplo", "municipio": "Brasília", "uf": "DF", "area": "Cultura", "na_rede": true }tipo é organizacao, empresa ou orgao. na_rede é sempre true (a resposta só existe para quem está na rede). Nunca saem e-mail, telefone, nome de pessoa nem endereço completo.
GET /acompanhamentos e GET /acompanhamentos/{id} (escopo rede:ler). São os trabalhos fechados da conta da chave, os mesmos que ela vê na ficha do cliente. Mostram o título, o estado (ativo, concluido ou cancelado), se o cliente já confirmou pelo link, os marcos e o estado de cada um (a_fazer, entregue, ajuste_pedido, aprovado) e o nome do cliente. Não saem valor, contato, CNPJ nem notas do cliente; o id de um trabalho de outra conta responde 404 acompanhamento_nao_encontrado.
{
"id": "5d1f7a52-3c80-4e0b-8c1c-2a6a8f9b4e10", "titulo": "Site novo", "estado": "ativo", "fechado_em": "2026-11-10",
"confirmado_pelo_cliente": true, "cliente_nome": "Associação Exemplo",
"marcos": [
{ "titulo": "Layout", "data_prevista": "2026-12-01", "estado": "aprovado" },
{ "titulo": "No ar", "data_prevista": null, "estado": "a_fazer" }
]
}O link que o cliente recebe não é um recurso desta API: ele abre uma página própria, sem conta, e a plataforma não o envia (quem presta o serviço envia, pelo canal dela).
Avisos (webhook)
Quando a chave tem URL de webhook, os eventos abaixo seguem o mesmo envelope, a mesma assinatura HMAC e a mesma política de tentativas do webhook de peças. Como lá, o aviso só diz que algo mudou: busque o recurso pela API.
| Evento | Quando |
|---|---|
oportunidade.candidatura_recebida | Chegou candidatura numa oportunidade da conta |
candidatura.escolhida / candidatura.recusada | A conta candidata foi escolhida ou não |
contrato.proposto, contrato.ativo, contrato.recusado | O contrato mudou de estado |
marco.entregue, entrega.decidida, marco.pago | Andamento de um marco |
avaliacao.liberada | A avaliação da contraparte ficou legível |
Erros da rede
Mesmo formato de erro da seção acima, mais estes códigos.
| Status | Código | Quando |
|---|---|---|
| 403 | conta_nao_verificada, sem_permissao, plano_nao_permite | Conta sem verificação, sem permissão para a ação ou fora do plano |
| 404 | oportunidade_nao_encontrada, candidatura_nao_encontrada, contrato_nao_encontrado, marco_nao_encontrado, entrega_nao_encontrada, entidade_nao_encontrada, acompanhamento_nao_encontrado | Inexistente, de outra conta ou, no diretório, organização que não está na rede |
| 409 | candidatura_repetida, oportunidade_fechada, estado_invalido, avaliacao_repetida | A ação não cabe no estado atual |
| 422 | limite_candidaturas, valor_invalido, marcos_invalidos, nps_invalido, comentario_obrigatorio, cnpj_invalido | Dados da ação ou limite do plano |
English
This API lets your client's own system (portal, intranet, dashboard) list the pieces Typemedia sent for approval, show their files and record the decision: approve, or request changes. The client approves in their own system and never needs an account here.
Each key belongs to one client of one account, and only sees that client's pieces.
Authentication
Send the key in the Authorization header. The account owner, partner or administrator creates keys under Conta → Integrações de parceiros. The key is shown once, as tmp_<8 chars>_<64 chars>. Keep it on your server, never in code the browser downloads. A key with the aprovacoes:decidir scope only works server to server: a browser call (with an Origin header) using it is refused with 403 chave_so_servidor; for browsers use a read-only key.
Authorization: Bearer tmp_1a2b3c4d_...Base URL: https://typemedia.com.br/api/parceiros/v1
Key scopes: aprovacoes:ler (list and read pieces) and aprovacoes:decidir (approve or request changes).
List pieces
GET /pecas?estado=em_aprovacao&limite=50&deslocamento=0
estado is optional: em_aprovacao (awaiting approval), ajuste_pedido (changes requested), aprovada, agendada or publicada. Drafts and archived pieces never appear. limite (page size) goes up to 100; deslocamento is the offset.
curl -H "Authorization: Bearer $KEY" \
"https://typemedia.com.br/api/parceiros/v1/pecas?estado=em_aprovacao"The response has total, limite, deslocamento and dados, an array of pieces (id, titulo, formato, canal, estado, data_prevista, versao_atual, atualizada_em).
Read a piece
GET /pecas/{id}
Returns versions, the message the team wrote for the client (mensagem), the comments visible to the client, and the files. Each file has a signed url valid for 5 minutes; fetch the piece again for a fresh URL. Internal team notes never leave the API. A piece of another client answers 404, the same as a piece that does not exist.
curl -H "Authorization: Bearer $KEY" \
https://typemedia.com.br/api/parceiros/v1/pecas/6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11Decide
POST /pecas/{id}/decisao with JSON { "decisao": "aprovar" | "ajuste", "nome": "...", "comentario": "..." }.
nome is required (who decided, up to 120 characters). comentario is optional when approving and required when requesting changes (up to 5000 characters). It only works while the piece is em_aprovacao. The decision is recorded with the given name and the key used.
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"decisao":"aprovar","nome":"Maria da Silva"}' \
https://typemedia.com.br/api/parceiros/v1/pecas/6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11/decisaoThe response is { "id": "...", "estado": "aprovada" | "ajuste_pedido", "versao": 2 }.
Webhook
If the key has a webhook URL, we send a JSON POST when a piece of that client enters approval (peca.em_aprovacao) or receives a new version while already in approval (peca.versao_nova). A new version on a piece that was in changes-requested or approved state returns it to approval and produces a single peca.em_aprovacao event. The body is shown in the Portuguese section above. The notice only says something changed: fetch the piece through the API for its content.
Headers: X-Typemedia-Assinatura: sha256=<hex HMAC-SHA256 of the raw body using the webhook secret>, X-Typemedia-Evento (the event) and X-Typemedia-Entrega (delivery id, equal to the body id; use it to ignore repeats).
Verifying the signature (Node.js): compute the HMAC over the body exactly as received (before parsing) and compare in constant time, as in the code sample above. Also check ocorrido_em against your clock and reject stale notices. Answer with a 2xx status within 5 seconds. On failure we retry up to 3 times in total (now, after 2 s, after 8 s); then the delivery is marked "Falhou" and can be resent from the screen. The URL must be public https:// on port 443 (we connect to the IP we checked); redirects are not followed.
Limits and CORS
- 120 calls per minute per key. Beyond that:
429withRetry-After(seconds). Every response carriesX-RateLimit-LimitandX-RateLimit-Remaining. - Server-to-server calls need no CORS. To call from a browser, register your site (for example
https://portal.example.com) on the key; only those origins getAccess-Control-Allow-Origin. There is no*. Only read keys work from a browser: a key withaprovacoes:decidiris refused (chave_so_servidor); send decisions from your server. Always prefer calling from your server so the key is not exposed. - Attempts with an invalid key are limited per IP address (60 per minute): beyond that,
429.
Errors
Every error is { "erro": { "codigo": "...", "mensagem": "..." } }. Status codes: 400 malformed request (estado_invalido, parametros_invalidos, json_invalido, decisao_invalida); 401 missing, wrong, revoked or inactive key (nao_autorizado, chave_invalida, chave_revogada, chave_inativa); 403 missing scope, unregistered origin, or a deciding key used from a browser (sem_escopo, origem_nao_permitida, chave_so_servidor); 404 piece not found or of another client (peca_nao_encontrada); 409 piece not awaiting a decision (peca_nao_esta_em_aprovacao); 422 invalid decision data (nome_obrigatorio, comentario_obrigatorio, comentario_longo); 429 rate limit (limite_excedido); 500 falha_interna.
Network, v1 (contract, not implemented)
> Status: a contract, not a service. Nothing in this section responds yet; the paths exist so the domain of those who hire (organizations, government, purpose-driven businesses) can be built on them. Today they return 404. Implementation starts when that domain opens; until then the contract only changes compatibly, and the change lands here before it lands in code.
This extends the API to the network's opportunities, applications, contracts, milestones and reviews. Whoever publishes and hires posts the opportunity, picks an applicant, approves deliveries, records payment and reviews; whoever provides the service applies, delivers and reviews. Rules (who may, in which state, which plan limit) live in the database and are the same as in the screens: the API has no rules of its own.
Authentication and key. Same Authorization: Bearer tmp_... header and key format. Difference: a network key is bound to one account (not a client) and acts on its behalf. What the account cannot do on screen (unverified account, pending membership, plan limit) the key cannot do either. Same management screen (Account → Partner integrations), same limite_por_minuto, origens and CORS rule.
| Scope | Allows |
|---|---|
rede:ler | List and read the account's opportunities, applications, contracts, milestones and reviews |
rede:escrever | Publish, apply, choose, answer a contract, deliver, decide a delivery, record payment and review |
Old name. These scopes used to be called marketplace:ler and marketplace:escrever. The old name is still accepted for now as equivalent to the new one: a key that already has it keeps working, and creating a new key offers only rede:ler and rede:escrever.
As with piece decisions, a key with rede:escrever only works server to server: with Origin or Sec-Fetch-Site it is refused with 403 chave_so_servidor. A request never switches accounts: the id of another account's resource returns 404, like a missing one.
Pagination, formats and retries. Every list takes limite (up to 100) and deslocamento and answers { "total", "limite", "deslocamento", "dados": [...] }. Dates are ISO 8601; amounts are numbers with two decimals (BRL). Every POST accepts an Idempotency-Key header (text up to 64 characters): repeating a key returns the first response without redoing the action.
Endpoints (all under /api/parceiros/v1):
- Opportunities:
GET /oportunidadesandGET /oportunidades/{id}(read; open ones, public fields only, filtered by the plan of the key's account as in the screen);POST /oportunidadesandPOST /oportunidades/{id}/fechamento(write; publisher). - Applications:
GET /oportunidades/{id}/candidaturas(read; publisher);POST /oportunidades/{id}/candidaturas(write; provider);GET /candidaturas(read; sent or received);POST /candidaturas/{id}/escolha(write; publisher; creates the contract with its milestones). - Contracts:
GET /contratos(filterestado) andGET /contratos/{id}(read; with milestones and history);POST /contratos/{id}/resposta(write; the party that has not answered;{ "decisao": "aceitar" }or{ "decisao": "recusar", "motivo": "..." }). - Milestones:
GET /contratos/{id}/marcos(read);POST /marcos/{id}/arquivos(write; provider; returns a signed upload URL valid for 5 minutes);POST /marcos/{id}/entrega(write; provider);POST /entregas/{id}/decisao(write; hiring side;aprovadaorajuste, comment required forajuste);POST /marcos/{id}/pagamento(write; hiring side; records a payment made outside the platform, which never moves money; approved milestones only). - Directory:
GET /diretorio?cnpj=<14 digits>(read; one organization by exact CNPJ, public fields only:cnpj,tipo,nome,municipio,uf,area,na_rede). The directory only has organizations that created an account, claimed their profile and are active; any other CNPJ answers404 entidade_nao_encontradaand a malformed one422 cnpj_invalido. No list, no search by name, no export. - Engagements:
GET /acompanhamentosandGET /acompanhamentos/{id}(read; the work closed with clients by the key's account, with title, stateativo,concluidoorcancelado, whether the client confirmed through the link, milestones and the state of each one, and the client's name only; no amount, contact, CNPJ or notes; another account'sidanswers404 acompanhamento_nao_encontrado). The link the client receives is not part of this API: it opens its own page, with no account. - Reviews:
GET /contratos/{id}/avaliacoes(read) andPOST /contratos/{id}/avaliacoes(write;momentofechamentoorentrega,nps0 to 10,nota_contraparte1 to 5,porque; one per account, contract and moment).
Opportunity fields (same as the screen shows to feed readers; conta_id and internal data never leave): id, conta_nome, titulo, descricao, area, nivel (aberta or verba_aprovada), valor_estimado, prazo, modalidade (remoto, presencial, hibrido), local, projeto_nome, criado_em. Request and response examples are in the Portuguese section above; field names are identical.
Contract states: proposto (waiting for the provider), aguardando_contratante (born from a commercial proposal; only the hiring account answers), ativo, concluido, cancelado, recusado. Contracts are a financial permission: the account must be verified, otherwise 403 conta_nao_verificada. Milestone states: a_fazer, entregue, aprovado, pago; the contract becomes concluido when the last milestone is pago. The fee the platform charges is not part of the API contract: it is a platform rule set in the database when the applicant is chosen, and it neither appears nor changes through the API.
Blind reviews. GET always returns the account's own review. The other party's nota_contraparte and porque become readable only when both accounts have answered the same moment or 14 days after the first answer (liberada_em); until then the fields are null. The platform nps is never shown to the counterpart.
Notices (webhook). If the key has a webhook URL, these events use the same envelope, HMAC signature and retry policy as the piece webhook, and only say that something changed: oportunidade.candidatura_recebida, candidatura.escolhida, candidatura.recusada, contrato.proposto, contrato.ativo, contrato.recusado, marco.entregue, entrega.decidida, marco.pago, avaliacao.liberada.
Network errors, in the same format, besides those above: 403 conta_nao_verificada, sem_permissao, plano_nao_permite; 404 oportunidade_nao_encontrada, candidatura_nao_encontrada, contrato_nao_encontrado, marco_nao_encontrado, entrega_nao_encontrada, entidade_nao_encontrada, acompanhamento_nao_encontrado; 409 candidatura_repetida, oportunidade_fechada, estado_invalido, avaliacao_repetida; 422 limite_candidaturas, valor_invalido, marcos_invalidos, nps_invalido, comentario_obrigatorio, cnpj_invalido.