{ "openapi": "3.1.0", "info": { "title": "NextChat · API de integração do Kanban", "version": "1.0.0", "description": "Requer instalação atualizada com kanban_integrations. Bearer API key criada em Configurações → Integrações → Kanban; a automação é executada pelo cliente. Limites por chave: 120 leituras/30 escritas por minuto; por empresa: 600/150. POSTs idempotentes e edição/movimentação com versão obrigatória." }, "servers": [ { "url": "https://app.nextchat.nextsistem.dev.br/api/integrations/v1", "description": "Substitua pela URL da sua instalação, incluindo eventual subcaminho." } ], "security": [ { "kanbanApiKey": [] } ], "paths": { "/me": { "get": { "operationId": "getIntegration", "summary": "Identificar a integração", "description": "Somente quadros permitidos; cartões privados e de canais privados são excluídos.", "tags": [ "Kanban" ], "parameters": [], "responses": { "200": { "description": "Sucesso", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Versão do cartão quando aplicável." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "true em repetição de POST concluído." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permissão insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de versão, idempotência ou regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo maior que 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Versão obrigatória", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até repetir." } } }, "503": { "description": "Falha temporária ou resultado incerto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "" } }, "/kanban/boards": { "get": { "operationId": "listBoards", "summary": "Listar quadros", "description": "Permissão: read. Somente quadros permitidos; cartões privados e de canais privados são excluídos.", "tags": [ "Kanban" ], "parameters": [ { "name": "archived", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ] } } ], "responses": { "200": { "description": "Sucesso", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Versão do cartão quando aplicável." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "true em repetição de POST concluído." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Board" } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permissão insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de versão, idempotência ou regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo maior que 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Versão obrigatória", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até repetir." } } }, "503": { "description": "Falha temporária ou resultado incerto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/kanban/boards/{id}": { "get": { "operationId": "getBoard", "summary": "Consultar quadro", "description": "Permissão: read. Somente quadros permitidos; cartões privados e de canais privados são excluídos.", "tags": [ "Kanban" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Versão do cartão quando aplicável." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "true em repetição de POST concluído." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permissão insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de versão, idempotência ou regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo maior que 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Versão obrigatória", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até repetir." } } }, "503": { "description": "Falha temporária ou resultado incerto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/kanban/cards": { "get": { "operationId": "listCards", "summary": "Buscar cartões", "description": "Permissão: read. Somente quadros permitidos; cartões privados e de canais privados são excluídos.", "tags": [ "Kanban" ], "parameters": [ { "name": "board_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 } }, { "name": "priority", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] } }, { "name": "label", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "due", "in": "query", "schema": { "type": "string", "enum": [ "any", "today", "week", "overdue", "none" ] } }, { "name": "tz", "in": "query", "schema": { "type": "string", "default": "America/Sao_Paulo" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "all", "open", "closed" ] } }, { "name": "archived", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "updated", "created", "due" ], "default": "updated" } } ], "responses": { "200": { "description": "Sucesso", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Versão do cartão quando aplicável." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "true em repetição de POST concluído." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardPage" } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permissão insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de versão, idempotência ou regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo maior que 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Versão obrigatória", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até repetir." } } }, "503": { "description": "Falha temporária ou resultado incerto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/kanban/cards/{id}": { "get": { "operationId": "getCard", "summary": "Consultar cartão e checklist", "description": "Permissão: read. Somente quadros permitidos; cartões privados e de canais privados são excluídos.", "tags": [ "Kanban" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Versão do cartão quando aplicável." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "true em repetição de POST concluído." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permissão insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de versão, idempotência ou regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo maior que 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Versão obrigatória", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até repetir." } } }, "503": { "description": "Falha temporária ou resultado incerto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" }, "patch": { "operationId": "updateCard", "summary": "Editar cartão", "description": "Permissão: update. Somente quadros permitidos; cartões privados e de canais privados são excluídos.", "tags": [ "Kanban" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "schema": { "type": "string" }, "description": "Ex.: \"v1\". Obrigatório se o JSON não tiver version." } ], "responses": { "200": { "description": "Sucesso", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Versão do cartão quando aplicável." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "true em repetição de POST concluído." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permissão insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de versão, idempotência ou regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo maior que 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Versão obrigatória", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até repetir." } } }, "503": { "description": "Falha temporária ou resultado incerto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCard" } } } }, "x-required-scope": "update" } }, "/kanban/boards/{id}/cards": { "post": { "operationId": "createCard", "summary": "Criar cartão", "description": "Permissão: create. Somente quadros permitidos; cartões privados e de canais privados são excluídos.", "tags": [ "Kanban" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Única por operação; repetir com mesmo corpo por até 7 dias. Reservas pendentes retornam 409 e nunca reexecutam." } ], "responses": { "201": { "description": "Sucesso", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Versão do cartão quando aplicável." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "true em repetição de POST concluído." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permissão insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de versão, idempotência ou regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo maior que 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Versão obrigatória", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até repetir." } } }, "503": { "description": "Falha temporária ou resultado incerto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCard" } } } }, "x-required-scope": "create" } }, "/kanban/cards/{id}/move": { "post": { "operationId": "moveCard", "summary": "Mover cartão", "description": "Permissão: move. Somente quadros permitidos; cartões privados e de canais privados são excluídos.", "tags": [ "Kanban" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Única por operação; repetir com mesmo corpo por até 7 dias. Reservas pendentes retornam 409 e nunca reexecutam." }, { "name": "If-Match", "in": "header", "schema": { "type": "string" }, "description": "Ex.: \"v1\". Obrigatório se o JSON não tiver version." } ], "responses": { "200": { "description": "Sucesso", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Versão do cartão quando aplicável." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "true em repetição de POST concluído." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permissão insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de versão, idempotência ou regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo maior que 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Versão obrigatória", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até repetir." } } }, "503": { "description": "Falha temporária ou resultado incerto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveCard" } } } }, "x-required-scope": "move" } }, "/kanban/cards/{id}/comments": { "post": { "operationId": "addComment", "summary": "Adicionar comentário", "description": "Permissão: comments:write. Somente quadros permitidos; cartões privados e de canais privados são excluídos.", "tags": [ "Kanban" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Única por operação; repetir com mesmo corpo por até 7 dias. Reservas pendentes retornam 409 e nunca reexecutam." } ], "responses": { "201": { "description": "Sucesso", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Versão do cartão quando aplicável." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "true em repetição de POST concluído." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permissão insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de versão, idempotência ou regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo maior que 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Versão obrigatória", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até repetir." } } }, "503": { "description": "Falha temporária ou resultado incerto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddComment" } } } }, "x-required-scope": "comments:write" } }, "/kanban/cards/{id}/checklist": { "post": { "operationId": "addChecklist", "summary": "Adicionar checklist", "description": "Permissão: checklist:write. Somente quadros permitidos; cartões privados e de canais privados são excluídos.", "tags": [ "Kanban" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Única por operação; repetir com mesmo corpo por até 7 dias. Reservas pendentes retornam 409 e nunca reexecutam." } ], "responses": { "201": { "description": "Sucesso", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Versão do cartão quando aplicável." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "true em repetição de POST concluído." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistItem" } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permissão insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de versão, idempotência ou regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo maior que 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Versão obrigatória", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até repetir." } } }, "503": { "description": "Falha temporária ou resultado incerto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddChecklist" } } } }, "x-required-scope": "checklist:write" } }, "/kanban/checklist/{id}": { "patch": { "operationId": "updateChecklist", "summary": "Editar checklist", "description": "Permissão: checklist:write. Somente quadros permitidos; cartões privados e de canais privados são excluídos.", "tags": [ "Kanban" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Versão do cartão quando aplicável." }, "Idempotency-Replayed": { "schema": { "type": "boolean" }, "description": "true em repetição de POST concluído." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistItem" } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave inválida, expirada ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permissão insuficiente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflito de versão, idempotência ou regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo maior que 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Versão obrigatória", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até repetir." } } }, "503": { "description": "Falha temporária ou resultado incerto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChecklist" } } } }, "x-required-scope": "checklist:write" } } }, "components": { "securitySchemes": { "kanbanApiKey": { "type": "http", "scheme": "bearer", "description": "Chave nck_… gerada no app; nunca um token de sessão." } }, "schemas": { "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error", "code" ] }, "Label": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } }, "ChecklistItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "text": { "type": "string" }, "done": { "type": "boolean" }, "position": { "type": "number" }, "done_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Stage": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "board_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "position": { "type": "integer" }, "kind": { "type": "string", "enum": [ "open", "won", "lost" ] }, "card_count": { "type": "integer" }, "overdue_count": { "type": "integer" } } }, "Board": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "archived": { "type": "boolean" }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/Stage" } }, "card_count": { "type": "integer" }, "overdue_count": { "type": "integer" } } }, "Card": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "board_id": { "type": "string", "format": "uuid" }, "board_name": { "type": "string" }, "stage_id": { "type": "string", "format": "uuid" }, "stage_name": { "type": "string" }, "stage_kind": { "type": "string" }, "position": { "type": "number" }, "title": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } }, "version": { "type": "integer", "minimum": 1 }, "archived": { "type": "boolean" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "checklist_total": { "type": "integer" }, "checklist_done": { "type": "integer" }, "checklist": { "type": "array", "items": { "$ref": "#/components/schemas/ChecklistItem" } } } }, "CardPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ] }, "Identity": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "board_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Comment": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CreateCard": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 200, "minLength": 1 }, "description": { "type": "string", "x-max-bytes": 10000, "description": "Máximo de 10.000 bytes em UTF-8." }, "stage_id": { "type": "string", "format": "uuid" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "label_ids": { "type": "array", "maxItems": 20, "items": { "type": "string", "format": "uuid" } }, "checklist": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 300 } } }, "required": [ "title" ] }, "UpdateCard": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 200, "minLength": 1 }, "description": { "type": "string", "x-max-bytes": 10000, "description": "Máximo de 10.000 bytes em UTF-8." }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "label_ids": { "type": "array", "maxItems": 20, "items": { "type": "string", "format": "uuid" } }, "version": { "type": "integer", "minimum": 1 } } }, "MoveCard": { "type": "object", "additionalProperties": false, "properties": { "stage_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "before_id": { "type": "string", "format": "uuid" }, "after_id": { "type": "string", "format": "uuid" }, "place": { "type": "string", "enum": [ "start", "end" ] } }, "required": [ "stage_id" ] }, "AddComment": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "text" ] }, "AddChecklist": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "text" ] }, "UpdateChecklist": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 300 }, "done": { "type": "boolean" } } } } }, "x-scopes": [ { "id": "read", "description": "Consultar quadros, etapas e cartões." }, { "id": "create", "description": "Criar cartões nos quadros selecionados." }, { "id": "update", "description": "Editar título, descrição, prioridade, prazo e etiquetas." }, { "id": "move", "description": "Mover cartões entre etapas do mesmo quadro." }, { "id": "comments:write", "description": "Adicionar comentários ao cartão." }, { "id": "checklist:write", "description": "Adicionar itens e atualizar seu texto ou conclusão." } ] }