PT EN

Pedidos de apoio

URL base: $BUSINESS_API

O objecto

idstring · opcional
tenant_idstring · opcional
customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · opcional
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

categorystring · opcional
subjectstring · opcional
statusstring · opcional
O objecto
{
  "id": "sup_2AubVo0zrAeLjY6td0mzN2sbbOI",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "category": "category",
  "subject": "Fuga na Rua 3",
  "status": "active"
}

Listar pedidos de apoio

Registos

GET /tickets

Returns the tenant's support tickets in cursor pages (limit up to 100, 20 by default, after for the next page). Query parameters customer_id, account_id, category, status and assigned_to filter exactly, and q searches ticket text and matching account holders. Requires support:read.

Parâmetros

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Support tickets

Mostrar atributos
dataarray of SupportTicket · obrigatório
Mostrar atributos filhos
idstring · opcional
tenant_idstring · opcional
customer_idstring · opcional
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · opcional
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

categorystring · opcional
subjectstring · opcional
statusstring · opcional
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 403

Permissões support:read · Funções: admin, analyst, customer_service, owner, viewer

curl -X GET "$BUSINESS_API/tickets" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "sup_2AubVo0zrAeLjY6td0mzN2sbbOI",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
      "customer_name": "Ana Matsinhe",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "category": "category",
      "subject": "Fuga na Rua 3",
      "status": "active"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Abrir um pedido de apoio

Registos

POST /tickets

Requires support:write. customer_id and account_id must be records of this utility; a ticket naming an account is visible to consumers linked to that account.

Corpo application/json

customer_idstring · opcional
account_idstring · opcional
categorystring · opcional
subjectstring · obrigatório
descriptionstring · obrigatório
prioritystring · opcional

Devolve

201 Support ticket created

Erros 400 · 403

Permissões support:write · Funções: admin, customer_service, owner

curl -X POST "$BUSINESS_API/tickets" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "category": "category",
  "subject": "Fuga na Rua 3",
  "description": "Leitura confirmada no local.",
  "priority": "priority"
}'
Resposta 201

Support ticket created

Obter um pedido de apoio

Registos

GET /tickets/{id}

Returns one ticket with its subject, description, category, priority, status, assignee and resolution. Returns 404 when the ticket is not in the caller's tenant; requires support:read.

Parâmetros

idstring · caminho · obrigatório

ID of the support ticket in the caller's tenant.

Devolve

200 Support ticket details

Erros 403 · 404

Permissões support:read · Funções: admin, analyst, customer_service, owner, viewer

curl -X GET "$BUSINESS_API/tickets/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Support ticket details

Atribuir um pedido de apoio

Registos

POST /tickets/{id}/assign

Sets assigned_to on the ticket to the given staff user ID and, if the ticket was open, moves it to in_progress. The assignee is not validated, and an empty value clears the assignment. Returns 404 for an unknown ticket; requires support:write.

Parâmetros

idstring · caminho · obrigatório

ID of the support ticket in the caller's tenant.

Devolve

200 Support ticket assigned

Erros 403 · 404

Permissões support:write · Funções: admin, customer_service, owner

curl -X POST "$BUSINESS_API/tickets/{id}/assign" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Support ticket assigned

Resolver um pedido de apoio

Registos

POST /tickets/{id}/resolve

Sets the ticket to resolved, stores the resolution text from the body and records the resolution time. The current status is not checked, so a closed ticket can be resolved again and the resolution overwritten. Returns 404 for an unknown ticket; requires support:write.

Parâmetros

idstring · caminho · obrigatório

ID of the support ticket in the caller's tenant.

Devolve

200 Support ticket resolved

Erros 403 · 404

Permissões support:write · Funções: admin, customer_service, owner

curl -X POST "$BUSINESS_API/tickets/{id}/resolve" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Support ticket resolved

Fechar um pedido de apoio

Registos

POST /tickets/{id}/close

Sets the ticket status to closed and returns it. The current status is not checked, so any ticket, resolved or not, can be closed and the call can be repeated. Returns 404 for an unknown ticket; requires support:write.

Parâmetros

idstring · caminho · obrigatório

ID of the support ticket in the caller's tenant.

Devolve

200 Support ticket closed

Erros 403 · 404

Permissões support:write · Funções: admin, customer_service, owner

curl -X POST "$BUSINESS_API/tickets/{id}/close" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Support ticket closed

Listar comentários de um pedido de apoio

Registos

GET /tickets/{id}/comments

Returns the comments on the ticket, from staff and from the customer, each marked with its author type, in cursor pages using limit (up to 100, 20 by default) and after. Returns 404 when the ticket is not in the caller's tenant; requires support:read.

Parâmetros

idstring · caminho · obrigatório

ID of the support ticket whose comments are listed.

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Comments

Erros 403 · 404

Permissões support:read · Funções: admin, analyst, customer_service, owner, viewer

curl -X GET "$BUSINESS_API/tickets/{id}/comments" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Comments

Comentar um pedido de apoio

Registos

POST /tickets/{id}/comments

Adds a staff comment with the given content to the ticket and updates the ticket's last-changed time; the ticket status is not changed. content is required (400 when empty) and the ticket must be in the caller's tenant (404 otherwise). Requires support:read and support:write.

Parâmetros

idstring · caminho · obrigatório

ID of the support ticket being commented on.

Devolve

201 Comment added

Erros 403 · 404

Permissões support:write · Funções: admin, customer_service, owner

curl -X POST "$BUSINESS_API/tickets/{id}/comments" \
  -H "Authorization: Bearer sk_test_..."
Resposta 201

Comment added

Obter os metadados de um pedido de apoio

Registos

GET /tickets/{id}/metadata

Returns the free-form key-value metadata the tenant has stored on the ticket, as an entry with resource_type, resource_id and a metadata map. The ticket must exist in the caller's tenant (404 otherwise); requires business:metadata:read.

Parâmetros

idstring · caminho · obrigatório

ID of the support ticket in the caller's tenant, at most 120 characters.

Devolve

200 Metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 404

Permissões business:metadata:read · Funções: admin, customer_service, owner

curl -X GET "$BUSINESS_API/tickets/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Actualizar os metadados de um pedido de apoio

Registos

PUT /tickets/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the keys in the metadata object into what the ticket already has; keys not sent are kept, and a key sent with an empty string is removed. Keys must be non-blank, at most 40 characters, without square brackets or control characters, values at most 500 characters, and a resource holds at most 50 keys; violations return 400 with one entry per invalid key. Returns the full metadata after the merge; requires business:metadata:write.

Parâmetros

idstring · caminho · obrigatório

ID of the support ticket in the caller's tenant, at most 120 characters.

Corpo application/json

metadataobject · obrigatório

Devolve

200 Resulting metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 400 · 404

Permissões business:metadata:write · Funções: admin, owner

curl -X PUT "$BUSINESS_API/tickets/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}