Abrir card de outro sistema

Um pedido de compra nasce no ERP, uma solicitação de acesso nasce no portal interno, uma ocorrência nasce no app de campo. Em vez de alguém redigitar, o sistema de origem abre o card no fluxo da TAI — com os campos preenchidos e os arquivos anexados — e o fluxo segue com as fases, aprovações e automações configuradas.


Quando usar	Um sistema seu precisa iniciar ou fazer andar um processo na TAI
Porta	REST · Agente (MCP) · formulário público (para pessoas, sem login)
Você vai precisar	módulo `GESTAO_PROCESSOS`; permissão `PROCESSO` para ler fluxos e listas de cards; acesso de Contribuidor ao fluxo (aba Visibilidade) para criar e mover; JWT de um usuário de integração vinculado a um colaborador

Como funciona

seu sistema ──► GET  /pipe/page?search=Compras            (uma vez: id do fluxo)
            ──► GET  /phase/by-pipe/{pipeId}              (uma vez: ids das fases)
            ──► GET  /field-schema/by-pipe/{pipeId}       (uma vez: id × identificador dos campos)
            ──► POST /card                                 (cria, com os valores: guarda id e numero)
            ──► POST /bpm/ged/upload/{cardId}/{campoId}    (arquivos, se houver)
            ──► POST /card/{id}/mover/{phaseId} | /submit  (faz andar)

Passo a passo

Ache o fluxo e as fases. Faça uma vez e guarde no seu sistema.

curl -s "https://api.taitecnologia.com/pipe/page?search=Compras" \
  -H "Authorization: Bearer $TAI_TOKEN"

curl -s https://api.taitecnologia.com/phase/by-pipe/14 \
  -H "Authorization: Bearer $TAI_TOKEN"

De cada fase, guarde id, nome, ordem, tipo (INICIO, PROCESSAMENTO, APROVACAO, FINALIZACAO), isDone (fase de conclusão) e requerAprovacao.

Leia os campos do fluxo.
Terminal window
```
curl -s https://api.taitecnologia.com/field-schema/by-pipe/14 \
  -H "Authorization: Bearer $TAI_TOKEN"
```
Monte um mapa identificador → id e anote o tipo e as opcoes de cada campo. Um campo só, pelo identificador: GET /field-schema/by-pipe/14/identificador/valor_total.

Crie o card com os valores. O card nasce na primeira fase do fluxo.

curl -s -X POST https://api.taitecnologia.com/card \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipe": { "id": 14 },
    "origemReferencia": "ERP-PC-4471",
    "fieldValues": [
      { "fieldSchemaId": 501, "valorTexto": "Notebooks para o time comercial" },
      { "fieldSchemaId": 502, "valorNumero": 12500.00 },
      { "fieldSchemaId": 503, "valorData": "2026-10-20" },
      { "fieldSchemaId": 504, "valorTexto": "Tecnologia" },
      { "fieldSchemaId": 505, "valorReferenciaId": 77 }
    ]
  }'

Cada valor vai no campo do seu tipo:

Tipo do campo	Propriedade
`TEXTO`, `TEXTO_LONGO`, `EMAIL`, `TELEFONE`, `CPF`, `CNPJ`, `LINK`, `SELECT`	`valorTexto` (em `SELECT`, o texto exato de uma opção)
`NUMERO`, `MOEDA`, `PERCENTUAL`	`valorNumero` (decimal com ponto)
`DATA`, `DATETIME`	`valorData` (`2026-10-20` ou data e hora ISO)
`CHECKBOX`	`valorBoolean`
`COLABORADOR`, `DEPARTAMENTO`, `CENTRO_CUSTO`	`valorReferenciaId` (o id do registro)
`ARQUIVO`	Upload à parte (passo 4)

origemReferencia é texto livre: guarde nele a chave do seu sistema — ela volta em todo GET do card. A resposta traz o card criado; guarde id e numero.

Por que mandar os valores no POST: as automações de Solicitação Criada rodam logo depois da criação. Valores gravados depois, em outra chamada, podem não chegar a elas — um webhook com {{campo.valor_total}} sairia sem o valor.

Anexe arquivos aos campos do tipo Arquivo. multipart, parte arquivo:
Terminal window
```
curl -s -X POST https://api.taitecnologia.com/bpm/ged/upload/90412/506 \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -F "arquivo=@orcamento.pdf"
```
O arquivo vira um documento do GED ligado ao campo, com versões. Uma nova versão do mesmo campo: POST /bpm/ged/upload-versao/{cardId}/{fieldSchemaId}. Para baixar: GET /bpm/ged/{cardId}/{fieldSchemaId}/download.

Atualize campos depois, pelo identificador. Sem precisar do id do campo:

curl -s -X POST https://api.taitecnologia.com/card-field-value/by-card/90412/batch \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "numero_pedido_erp": "PC-4471", "fornecedor": "Loja Exemplo" }'

As chaves são identificadores (ou ids numéricos). Essa gravação dispara as automações de Campo Alterado.

Faça o card andar. Três rotas, conforme o caso:

Rota	Quando usar
`POST /card/{id}/avancar`	Vai para a próxima fase (ordem + 1), validando os obrigatórios da fase atual
`POST /card/{id}/mover/{phaseId}?motivo=…`	Vai para uma fase específica. `validarCampos=false` pula a validação dos obrigatórios
`POST /card/{id}/submit`	Grava campos e avança no mesmo gesto: `{"campos": {"identificador": valor}, "phaseDestinoId": 63}`

Entrar numa fase marcada como Fase de Conclusão conclui o card (status CONCLUIDO). Para desistir: POST /card/{id}/cancelar?motivo=….

Comente, se precisar. Um registro do seu sistema no histórico do card:

curl -s -X POST https://api.taitecnologia.com/card-comment \
  -H "Authorization: Bearer $TAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cardId": 90412, "conteudo": "Pedido PC-4471 criado no ERP." }'

Automatize

Tudo o que o fluxo faz com um card criado na tela, faz com o criado pela API: automações de Solicitação Criada, SLA, responsável automático, aprovação.

Para o seu sistema saber como o card andou, assine num webhook os eventos do ciclo do card — Um card muda de fase (CARD_MOVIDO_FASE), Um card é concluído (CARD_CONCLUIDO), Um card é cancelado (CARD_CANCELADO), Um card é aprovado ou reprovado (CARD_APROVADO, CARD_REPROVADO). Cada um traz cardId, numero, pipeId, faseId e faseNome: case pelo cardId que você guardou no passo 3. Quando o seu sistema precisa responder a uma etapa e o card esperar por ele, veja Avisar o ERP quando o pedido é aprovado.

Se o seu sistema não consegue chamar a API com um token de usuário — só sabe disparar um POST para um endereço —, use um endereço de entrada e um fluxo automatizado que começa por Quando outro sistema chamar e abre o card com o bloco Abrir card num quadro.

Para pessoas de fora abrirem cards sem login, prefira o formulário público do fluxo.

Pelo seu agente de IA

“Abra uma solicitação no fluxo Compras: 3 notebooks para o comercial, R$ 12.500, para 20/10.”

É uma escrita, com aprovação no seu cliente de IA; o agente descobre os campos do fluxo antes de criar. “Em que fase está o pedido 1287 de Compras?” é leitura. Aprovar um card é ação de confirmação forte: o agente externo não a executa — veja Aprovações.

Cuidados

O usuário de integração precisa ser colaborador. Criar e mover exigem acesso ao fluxo — criador, responsável ou compartilhamento de Contribuidor (aba Visibilidade do fluxo) — e isso só vale para um usuário vinculado a um colaborador. Sem isso, 403 — “Você não tem permissão para criar cards neste fluxo”. O colaborador vira o criador do card ({{criador.nome}} nos webhooks).
Não há chave de idempotência. Repetir o POST /card cria outro card. Guarde o id da resposta antes de seguir; depois de um tempo esgotado, confira os cards recentes (GET /card/by-pipe/{pipeId}/page?sort=id,desc&size=20) procurando o seu origemReferencia.
Identificador desconhecido é ignorado em /card-field-value/.../batch e em /submit, sem erro. Confira os identificadores no passo 2.
Obrigatórios barram o avanço: 400 com {"valido": false, "camposFaltantes": […]}. Para conferir antes, GET /card/{id}/validar-fase-atual.
Regras de movimento valem para a API: fases com destinos permitidos e limite de cards recusam o movimento com 400, e um card numa fase de aprovação só sai depois de aprovado.
Corpo com URL (um campo LINK com https://…) ou acima de 8 KB pode ser recusado pelo firewall com 403 sem JSON. Veja Limites de uso.
Datas e números: Datas e formatos.

Referência gerada do contrato da API em 30 de outubro de 2026. taitecnologia.com · Termos de uso · Privacidade