cord-sdk 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,4 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ dist/
4
+ .pytest_cache/
@@ -0,0 +1,48 @@
1
+ # Changelog
2
+
3
+ ## [1.1.0] — 2026-11-04
4
+
5
+ ### Added
6
+
7
+ - `AsyncCord`: el mismo cliente con `await` y `async for`, sobre httpx (`pip install 'cord-sdk[async]'`) o el `transport` que pases. Comparte con `Cord` la idempotencia, los reintentos y los errores.
8
+ - `cord.types`: un `TypedDict` por objeto de la API, generado de la spec OpenAPI (`npm run sdk:types`), con los mismos nombres que el SDK de Node. Los argumentos de `create`, `update`, `list` y `list_all` están tipados y el paquete pasa `mypy --strict`.
9
+ - Un `Decimal` se manda como número y un `date` o `datetime` como fecha ISO 8601, en el cuerpo y en los filtros (antes, un `TypeError`); un booleano en un filtro va como `true` o `false`.
10
+ - `cord.workflows.invoke(workflow_id, objeto, ids)`: corre un workflow "Lo corres tú" sobre cotizaciones o facturas (`POST /workflows/{id}/invoke`).
11
+ - `cord.setup.propose(sitio=, descripcion=, archivo=)` y `cord.setup.retrieve(plan_id)`: propone una configuración de la cuenta y consulta su estado (`/setup/plans`).
12
+ - `cord.elements.config()`. `cord.elements_config()` sigue funcionando.
13
+ - `invoices.finalize(invoice_id, sin_comercio_exterior=True)`: confirma que un CFDI a un cliente extranjero no lleva mercancías.
14
+ - `verify_signature(payload, headers, secret)`: comprueba la firma de cualquier envío de Cord sin leer el cuerpo.
15
+ - `construct_workflow_delivery(payload, headers, secret)`: verifica y decodifica el POST de la acción "Mandar los datos a una URL" de Cord Workflows.
16
+ - `construct_event`, `verify_signature` y `construct_workflow_delivery` aceptan también Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`); con las dos firmas basta con que cuadre una. Las tres cuelgan también de `cord.webhooks`.
17
+ - `create_task()` acepta `factura_id`.
18
+ - `quotes.update(quote_id, **params)`: edita un borrador; lo que pasas reemplaza a lo guardado y lo que no pasas se conserva.
19
+ - `products.retrieve`, `products.update` y `products.delete` (`/productos/{id}`).
20
+ - `webhook_endpoints.update(endpoint_id, url=, eventos=, activo=)` y `webhook_endpoints.rotate_secret(endpoint_id, ventana_horas=None)`: el secreto anterior sigue firmando 1, 24 o 72 horas junto al nuevo.
21
+ - `test_helpers.reset()`: vacía los datos del entorno de prueba y conserva las llaves y los endpoints de webhook.
22
+ - `cord.raw_request(method, path, query=, body=, idempotency_key=, headers=)` devuelve un `RawResponse` (`data`, `meta`, `request_id`, `last_response`): una ruta sin método propio con la llave, la idempotencia, los reintentos y los errores ya puestos. La ruta es relativa a `/api/v1`; una URL absoluta, `//host`, `.` o `..` son un `ValueError` antes de la red.
23
+ - `cord.last_response`: un `CordResponse` (`status`, `headers`, `request_id`, `idempotent_replayed`, `api_version`) de la última llamada exitosa, guardado en una variable de contexto: correcto por hilo y por tarea de asyncio.
24
+ - `cord.with_options(timeout=, max_retries=)`: un cliente con otras opciones que comparte transporte y `last_response` con el original.
25
+ - `app_info={"name": ..., "version": ...}` agrega tu app al `User-Agent` (`cord-python/1.1.0 mi-erp/4.2.0`).
26
+ - `CordError.headers` y `CordError.retry_after`.
27
+ - `API_VERSION` sale de `cord.types`, generado del contrato de la API, y la versión del paquete de `cord/_version.py`, que también lee `pyproject.toml`.
28
+
29
+ ### Changed
30
+
31
+ - Requiere Python 3.10 o posterior: Python 3.9 dejó de tener soporte en octubre de 2025.
32
+ - `idempotency_key` se pasa siempre por nombre. Antes era el primer argumento posicional de `create` y `update`: `cord.quotes.create({...})` mandaba el cuerpo vacío y metía el diccionario en el header `Idempotency-Key`. Ahora es un `TypeError`.
33
+ - Solo se reintenta un fallo de red (`ConnectionError`, `TimeoutError`, `URLError`). Antes cualquier excepción del transporte, también un `TypeError` del propio código, se reintentaba y se reportaba como `network_error`.
34
+ - `list_all()` recorre por cursor también cotizaciones, clientes y productos (antes por `offset`, que salta o repite registros si alguien escribe mientras recorres). Acepta `limit=` como tamaño de página, que antes lanzaba `TypeError`, y `products.list_all()` acepta filtros. Pasarle `offset` o `cursor` es un `TypeError`.
35
+ - Las firmas de los webhooks se verifican sobre los bytes crudos: un cuerpo que no es UTF-8 da `signature_mismatch` en lugar de `UnicodeDecodeError`, igual que en los SDK de Node y PHP.
36
+ - El transporte respeta `Cord-Should-Retry`: `false` no reintenta esa respuesta aunque sea un 5xx, y `true` la reintenta aunque su status no esté en la lista.
37
+ - Sin secreto, `construct_event` lanza `missing_secret` (antes `missing_signature`).
38
+ - Reintentos: `Cord-Should-Retry` manda siempre. Sin él se reintenta la red caída, `408`, `425` y `5xx`; un `429` solo con `code` `rate_limited` o sin `code`. Una cuota agotada (`api_quota_exceeded`, `ai_quota_exceeded`) sale de inmediato. Las esperas suman como mucho 60 s por llamada; un `Retry-After` que no cabe ya no se recorta: sale el error. `409 idempotency_in_progress` no gasta reintentos y se vuelve a preguntar hasta la respuesta guardada. `Retry-After` se lee también como fecha HTTP.
39
+ - Nunca sigue una redirección: el transporte de urllib usa un opener sin redirecciones (antes un `302` de un `POST` llegaba como `GET`) y httpx va con `follow_redirects=False`. Un `3xx` es `CordError` con `code` `unexpected_redirect`, sin reintento.
40
+ - Las pruebas verifican los vectores de `test/fixtures/webhook-vectors.json`, firmados con el firmador del servidor, los mismos que verifican los SDK de Node y PHP, con los casos de un `t` con dígitos que no son ASCII y de un cuerpo que no es UTF-8.
41
+
42
+ ## [1.0.0] — nunca publicada
43
+
44
+ Primera versión, en el repositorio; no se publicó en PyPI.
45
+
46
+ - API v1: cotizaciones, clientes, productos, facturas, cobranza, eventos, tareas, endpoints de webhook, configuración de Elements y `test_helpers`.
47
+ - `Idempotency-Key` automática en toda mutación, la misma en cada reintento; reintentos con `Retry-After`; errores `CordError` con `code`, `request_id` y `doc_url`.
48
+ - `construct_event` exige la firma V1 con timestamp; la legacy solo con `allow_legacy_signature=True`.
@@ -0,0 +1,211 @@
1
+ Metadata-Version: 2.5
2
+ Name: cord-sdk
3
+ Version: 1.1.0
4
+ Summary: SDK de Python para la API de Cord: cotizaciones, facturas, webhooks verificados, tipos y cliente async. Sin dependencias.
5
+ Project-URL: Homepage, https://cordhq.app
6
+ Project-URL: Documentation, https://docs.cordhq.app/docs/desarrolladores/herramientas/sdks
7
+ Project-URL: API reference, https://docs.cordhq.app/docs/desarrolladores/referencia
8
+ Author: Flouvia
9
+ License: MIT
10
+ Keywords: api,async,cord,cotizaciones,facturas,webhooks
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Framework :: AsyncIO
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Office/Business :: Financial
24
+ Classifier: Typing :: Typed
25
+ Requires-Python: >=3.10
26
+ Provides-Extra: async
27
+ Requires-Dist: httpx>=0.27; extra == 'async'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # cord-sdk (Python)
31
+
32
+ SDK de Python para la API de [Cord](https://cordhq.app). Sin dependencias, Python 3.10+, con tipos y cliente async.
33
+
34
+ ```bash
35
+ pip install cord-sdk
36
+ pip install 'cord-sdk[async]' # AsyncCord, con httpx
37
+ ```
38
+
39
+ ```python
40
+ from cord import Cord
41
+
42
+ cord = Cord("sk_test_...")
43
+ quote = cord.quotes.create(
44
+ cliente={"empresa": "Acme"},
45
+ items=[{"descripcion": "Instalación", "cantidad": 1, "precio_unitario": 12500, "tax_rate": 0.16}],
46
+ base_currency="MXN",
47
+ )
48
+ print(quote["folio"], quote["link_publico"])
49
+
50
+ for invoice in cord.invoices.list_all(estado="open"):
51
+ print(invoice["numero"], invoice["saldo"], invoice["moneda"])
52
+ ```
53
+
54
+ - Toda mutación lleva `Idempotency-Key`, la misma en cada reintento: un corte de red nunca duplica nada. Pasa `idempotency_key=` (siempre por nombre) para atarla a tu propio identificador.
55
+ - `list_all()` recorre por cursor: no salta ni repite registros aunque alguien escriba mientras recorres. Acepta los filtros de `list()` y `limit=` como tamaño de cada página.
56
+ - Los errores son `CordError` con `status`, `code`, `request_id`, `doc_url`, `headers` y `retry_after`. Un error de tu código, como un `TypeError`, sale tal cual y no se reintenta.
57
+ - Manda `Cord-Version: 2026-10-01`; cámbiala con `Cord(sk, api_version=...)`.
58
+ - Un `Decimal` se manda como número y un `date` o `datetime` como fecha ISO 8601, en el cuerpo y en los filtros. Los tipos siguen la spec (`float` y `str`), salvo `record_payment` y `credit_note`, que aceptan `Decimal`.
59
+
60
+ ## Reintentos
61
+
62
+ - Si la respuesta trae `Cord-Should-Retry`, manda ese header: `false` no se reintenta (una cuota agotada, el tope de envíos de una factura, un rechazo del PAC al emitir) y `true` sí.
63
+ - Sin él se reintenta la red caída (`ConnectionError`, `TimeoutError` o `URLError`), 408, 425 y 5xx. Un 429 solo si es de ritmo (`code` `rate_limited`) o llega sin `code`, como el de un proxy; uno de cuota agotada (`api_quota_exceeded`, `ai_quota_exceeded`) sale de inmediato.
64
+ - Se espera lo que diga `Retry-After` (segundos o fecha HTTP) o un backoff exponencial, y todas las esperas de una llamada suman como mucho 60 s. Si la siguiente no cabe, sale el `CordError`, con `retry_after` para que decidas tú cuándo volver.
65
+ - `409 idempotency_in_progress` (la misma clave sigue en curso) no gasta reintentos: el SDK vuelve a preguntar hasta recibir la respuesta guardada, así un `finalize` lento termina con la factura. `max_retries=0` apaga todo reintento.
66
+ - Nunca sigue una redirección: un 3xx es `CordError` con `code` `unexpected_redirect` y la dirección a la que apunta. Revisa `base_url` (la de producción es `https://cordhq.app`).
67
+
68
+ ## Opciones por llamada, respuesta y rutas sin método
69
+
70
+ ```python
71
+ cord = Cord("sk_test_...", app_info={"name": "mi-erp", "version": "4.2.0"}) # User-Agent: cord-python/1.1.0 mi-erp/4.2.0
72
+
73
+ rapido = cord.with_options(timeout=5.0, max_retries=0)
74
+ rapido.invoices.finalize(factura_id)
75
+ print(cord.last_response.request_id) # búscalo en Desarrolladores › Registros
76
+
77
+ r = cord.raw_request("GET", "/cotizaciones", query={"status": "sent", "limit": 5})
78
+ print(r.data, r.meta, r.request_id)
79
+ ```
80
+
81
+ - `with_options(timeout=, max_retries=)` devuelve un cliente con esas opciones que comparte transporte y `last_response` con el original.
82
+ - `last_response` es un `CordResponse` (`status`, `headers`, `request_id`, `idempotent_replayed`, `api_version`) de la última llamada exitosa de ese hilo o esa tarea de asyncio.
83
+ - `raw_request(method, path, query=, body=, idempotency_key=, headers=)` llama una ruta que el SDK aún no tiene como método, con la llave, `Cord-Version`, la idempotencia, los reintentos y los errores ya puestos, y devuelve un `RawResponse`. La ruta es relativa a `/api/v1` (`/api/v1/…` también vale); una URL absoluta, `//host`, `.` o `..` son un `ValueError`: la llave nunca sale a otro host.
84
+
85
+ ## Tipos
86
+
87
+ Cada respuesta es un `TypedDict` de `cord.types`, generado de la spec OpenAPI con los mismos nombres que el SDK de Node (`Quote`, `QuoteDetail`, `Invoice`, `InvoiceDetail`, `Client`, `Product`…). Los argumentos de `create`, `update`, `list` y `list_all` también están tipados: mypy o Pyright marcan un campo mal escrito antes de llamar a Cord.
88
+
89
+ ```python
90
+ from cord.types import InvoiceDetail
91
+
92
+ factura: InvoiceDetail = cord.invoices.retrieve(factura_id)
93
+ print(factura["saldo"], factura["moneda"])
94
+ ```
95
+
96
+ ## Async
97
+
98
+ ```python
99
+ from cord import AsyncCord
100
+
101
+ async with AsyncCord("sk_test_...") as cord:
102
+ quote = await cord.quotes.create(items=[{"descripcion": "Instalación", "cantidad": 1, "precio_unitario": 12500}])
103
+ async for invoice in cord.invoices.list_all(estado="open"):
104
+ print(invoice["numero"])
105
+ ```
106
+
107
+ `AsyncCord` tiene los mismos métodos que `Cord`, con la misma idempotencia y los mismos reintentos. Usa httpx; con `transport=` puedes pasar el tuyo (una función async que recibe `method, url, headers, body, timeout` y devuelve `status, headers, body`).
108
+
109
+ ## Recursos
110
+
111
+ | Atributo | Métodos |
112
+ |---|---|
113
+ | `cord.me()`, `cord.collections()`, `cord.create_task(...)` | `GET /me`, `GET /cobranza`, `POST /tareas` |
114
+ | `cord.quotes` | `list`, `list_all`, `retrieve`, `create`, `update`, `send`, `resend`, `approve`, `reject`, `mark_paid`, `delete`, `draft_from_text` |
115
+ | `cord.clients` | `list`, `list_all`, `retrieve`, `create`, `update` |
116
+ | `cord.products` | `list`, `list_all`, `retrieve`, `create`, `update`, `delete` |
117
+ | `cord.invoices` | `list`, `list_all`, `retrieve`, `create`, `finalize`, `send`, `void`, `record_payment`, `credit_note` |
118
+ | `cord.events` | `list`, `list_all` |
119
+ | `cord.workflows` | `invoke` |
120
+ | `cord.setup` | `propose`, `retrieve` |
121
+ | `cord.elements` | `config` |
122
+ | `cord.webhook_endpoints` | `list`, `create`, `update`, `rotate_secret`, `delete` |
123
+ | `cord.test_helpers` | `reset`, `set_next_fiscal_outcome`, `view_quote`, `expire_quote`, `trigger_webhook` (solo `sk_test_`) |
124
+ | `cord.webhooks` | `construct_event`, `construct_workflow_delivery`, `verify_signature`, `sign_payload` |
125
+
126
+ ```python
127
+ factura = cord.invoices.create(cliente_id=cliente_id, items=[...], currency="MXN")
128
+ # Un CFDI a un cliente extranjero sin mercancías: confírmalo al emitir.
129
+ cord.invoices.finalize(factura["id"], sin_comercio_exterior=True)
130
+
131
+ cord.workflows.invoke("wf_…", "invoice", [factura["id"]])
132
+
133
+ plan = cord.setup.propose(sitio="tunegocio.com", descripcion="Instalaciones eléctricas, cobro a 30 días")
134
+ print(plan["review_url"]) # una persona la aprueba ahí
135
+
136
+ cord.webhook_endpoints.update(endpoint_id, activo=False) # lo pausa
137
+ nuevo = cord.webhook_endpoints.rotate_secret(endpoint_id, 72)
138
+ print(nuevo["secret"], nuevo["secreto_anterior_expira"]) # el anterior sigue firmando 72 horas
139
+ ```
140
+
141
+ ## Webhooks
142
+
143
+ Verifica siempre sobre el cuerpo **crudo**, tal como llegó.
144
+
145
+ Flask:
146
+
147
+ ```python
148
+ import os
149
+ from flask import Flask, request
150
+ from cord import construct_event, WebhookSignatureError
151
+
152
+ app = Flask(__name__)
153
+
154
+ @app.post("/webhooks/cord")
155
+ def cord_webhook():
156
+ try:
157
+ event = construct_event(request.get_data(), request.headers, os.environ["CORD_WEBHOOK_SECRET"])
158
+ except WebhookSignatureError:
159
+ return "", 400
160
+ if event["event"] == "invoice.paid":
161
+ ...
162
+ return "ok"
163
+ ```
164
+
165
+ FastAPI:
166
+
167
+ ```python
168
+ import os
169
+ from fastapi import FastAPI, Request, Response
170
+ from cord import construct_event, WebhookSignatureError
171
+
172
+ app = FastAPI()
173
+
174
+ @app.post("/webhooks/cord")
175
+ async def cord_webhook(request: Request) -> Response:
176
+ try:
177
+ event = construct_event(await request.body(), request.headers, os.environ["CORD_WEBHOOK_SECRET"])
178
+ except WebhookSignatureError:
179
+ return Response(status_code=400)
180
+ if event["event"] == "invoice.paid":
181
+ ...
182
+ return Response("ok")
183
+ ```
184
+
185
+ En Django, el cuerpo crudo es `request.body` y la vista va con `@csrf_exempt`.
186
+
187
+ Usa el cuerpo crudo. Acepta `X-Cord-Signature-V1` o Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`), ambas con timestamp (5 minutos de tolerancia, `tolerance=`); con las dos basta con que cuadre una. La firma legacy solo con `allow_legacy_signature=True`. Deduplica por `event["id"]`.
188
+
189
+ `WebhookSignatureError.code`: `missing_secret`, `missing_signature`, `invalid_signature_header`, `timestamp_out_of_tolerance`, `signature_mismatch`, `legacy_signature_rejected` o `invalid_payload`.
190
+
191
+ ### El POST de un workflow
192
+
193
+ La acción "Mandar los datos a una URL" de Cord Workflows firma su POST igual, pero su cuerpo es `{ workflow, workflow_id, evento, objeto, objeto_id, enviado_en, mensaje?, datos }`:
194
+
195
+ ```python
196
+ from cord import construct_workflow_delivery
197
+
198
+ envio = construct_workflow_delivery(request.get_data(), request.headers, os.environ["CORD_WORKFLOW_SECRET"])
199
+ print(envio["evento"], envio["datos"])
200
+ ```
201
+
202
+ `verify_signature(payload, headers, secret)` solo comprueba la firma, sin leer el cuerpo.
203
+
204
+ ## Modo prueba
205
+
206
+ ```python
207
+ cord = Cord("sk_test_...")
208
+ cord.test_helpers.set_next_fiscal_outcome("pac_caido")
209
+ cord.test_helpers.trigger_webhook("invoice.paid")
210
+ cord.test_helpers.reset() # vacía el entorno de prueba; conserva llaves y endpoints
211
+ ```
@@ -0,0 +1,182 @@
1
+ # cord-sdk (Python)
2
+
3
+ SDK de Python para la API de [Cord](https://cordhq.app). Sin dependencias, Python 3.10+, con tipos y cliente async.
4
+
5
+ ```bash
6
+ pip install cord-sdk
7
+ pip install 'cord-sdk[async]' # AsyncCord, con httpx
8
+ ```
9
+
10
+ ```python
11
+ from cord import Cord
12
+
13
+ cord = Cord("sk_test_...")
14
+ quote = cord.quotes.create(
15
+ cliente={"empresa": "Acme"},
16
+ items=[{"descripcion": "Instalación", "cantidad": 1, "precio_unitario": 12500, "tax_rate": 0.16}],
17
+ base_currency="MXN",
18
+ )
19
+ print(quote["folio"], quote["link_publico"])
20
+
21
+ for invoice in cord.invoices.list_all(estado="open"):
22
+ print(invoice["numero"], invoice["saldo"], invoice["moneda"])
23
+ ```
24
+
25
+ - Toda mutación lleva `Idempotency-Key`, la misma en cada reintento: un corte de red nunca duplica nada. Pasa `idempotency_key=` (siempre por nombre) para atarla a tu propio identificador.
26
+ - `list_all()` recorre por cursor: no salta ni repite registros aunque alguien escriba mientras recorres. Acepta los filtros de `list()` y `limit=` como tamaño de cada página.
27
+ - Los errores son `CordError` con `status`, `code`, `request_id`, `doc_url`, `headers` y `retry_after`. Un error de tu código, como un `TypeError`, sale tal cual y no se reintenta.
28
+ - Manda `Cord-Version: 2026-10-01`; cámbiala con `Cord(sk, api_version=...)`.
29
+ - Un `Decimal` se manda como número y un `date` o `datetime` como fecha ISO 8601, en el cuerpo y en los filtros. Los tipos siguen la spec (`float` y `str`), salvo `record_payment` y `credit_note`, que aceptan `Decimal`.
30
+
31
+ ## Reintentos
32
+
33
+ - Si la respuesta trae `Cord-Should-Retry`, manda ese header: `false` no se reintenta (una cuota agotada, el tope de envíos de una factura, un rechazo del PAC al emitir) y `true` sí.
34
+ - Sin él se reintenta la red caída (`ConnectionError`, `TimeoutError` o `URLError`), 408, 425 y 5xx. Un 429 solo si es de ritmo (`code` `rate_limited`) o llega sin `code`, como el de un proxy; uno de cuota agotada (`api_quota_exceeded`, `ai_quota_exceeded`) sale de inmediato.
35
+ - Se espera lo que diga `Retry-After` (segundos o fecha HTTP) o un backoff exponencial, y todas las esperas de una llamada suman como mucho 60 s. Si la siguiente no cabe, sale el `CordError`, con `retry_after` para que decidas tú cuándo volver.
36
+ - `409 idempotency_in_progress` (la misma clave sigue en curso) no gasta reintentos: el SDK vuelve a preguntar hasta recibir la respuesta guardada, así un `finalize` lento termina con la factura. `max_retries=0` apaga todo reintento.
37
+ - Nunca sigue una redirección: un 3xx es `CordError` con `code` `unexpected_redirect` y la dirección a la que apunta. Revisa `base_url` (la de producción es `https://cordhq.app`).
38
+
39
+ ## Opciones por llamada, respuesta y rutas sin método
40
+
41
+ ```python
42
+ cord = Cord("sk_test_...", app_info={"name": "mi-erp", "version": "4.2.0"}) # User-Agent: cord-python/1.1.0 mi-erp/4.2.0
43
+
44
+ rapido = cord.with_options(timeout=5.0, max_retries=0)
45
+ rapido.invoices.finalize(factura_id)
46
+ print(cord.last_response.request_id) # búscalo en Desarrolladores › Registros
47
+
48
+ r = cord.raw_request("GET", "/cotizaciones", query={"status": "sent", "limit": 5})
49
+ print(r.data, r.meta, r.request_id)
50
+ ```
51
+
52
+ - `with_options(timeout=, max_retries=)` devuelve un cliente con esas opciones que comparte transporte y `last_response` con el original.
53
+ - `last_response` es un `CordResponse` (`status`, `headers`, `request_id`, `idempotent_replayed`, `api_version`) de la última llamada exitosa de ese hilo o esa tarea de asyncio.
54
+ - `raw_request(method, path, query=, body=, idempotency_key=, headers=)` llama una ruta que el SDK aún no tiene como método, con la llave, `Cord-Version`, la idempotencia, los reintentos y los errores ya puestos, y devuelve un `RawResponse`. La ruta es relativa a `/api/v1` (`/api/v1/…` también vale); una URL absoluta, `//host`, `.` o `..` son un `ValueError`: la llave nunca sale a otro host.
55
+
56
+ ## Tipos
57
+
58
+ Cada respuesta es un `TypedDict` de `cord.types`, generado de la spec OpenAPI con los mismos nombres que el SDK de Node (`Quote`, `QuoteDetail`, `Invoice`, `InvoiceDetail`, `Client`, `Product`…). Los argumentos de `create`, `update`, `list` y `list_all` también están tipados: mypy o Pyright marcan un campo mal escrito antes de llamar a Cord.
59
+
60
+ ```python
61
+ from cord.types import InvoiceDetail
62
+
63
+ factura: InvoiceDetail = cord.invoices.retrieve(factura_id)
64
+ print(factura["saldo"], factura["moneda"])
65
+ ```
66
+
67
+ ## Async
68
+
69
+ ```python
70
+ from cord import AsyncCord
71
+
72
+ async with AsyncCord("sk_test_...") as cord:
73
+ quote = await cord.quotes.create(items=[{"descripcion": "Instalación", "cantidad": 1, "precio_unitario": 12500}])
74
+ async for invoice in cord.invoices.list_all(estado="open"):
75
+ print(invoice["numero"])
76
+ ```
77
+
78
+ `AsyncCord` tiene los mismos métodos que `Cord`, con la misma idempotencia y los mismos reintentos. Usa httpx; con `transport=` puedes pasar el tuyo (una función async que recibe `method, url, headers, body, timeout` y devuelve `status, headers, body`).
79
+
80
+ ## Recursos
81
+
82
+ | Atributo | Métodos |
83
+ |---|---|
84
+ | `cord.me()`, `cord.collections()`, `cord.create_task(...)` | `GET /me`, `GET /cobranza`, `POST /tareas` |
85
+ | `cord.quotes` | `list`, `list_all`, `retrieve`, `create`, `update`, `send`, `resend`, `approve`, `reject`, `mark_paid`, `delete`, `draft_from_text` |
86
+ | `cord.clients` | `list`, `list_all`, `retrieve`, `create`, `update` |
87
+ | `cord.products` | `list`, `list_all`, `retrieve`, `create`, `update`, `delete` |
88
+ | `cord.invoices` | `list`, `list_all`, `retrieve`, `create`, `finalize`, `send`, `void`, `record_payment`, `credit_note` |
89
+ | `cord.events` | `list`, `list_all` |
90
+ | `cord.workflows` | `invoke` |
91
+ | `cord.setup` | `propose`, `retrieve` |
92
+ | `cord.elements` | `config` |
93
+ | `cord.webhook_endpoints` | `list`, `create`, `update`, `rotate_secret`, `delete` |
94
+ | `cord.test_helpers` | `reset`, `set_next_fiscal_outcome`, `view_quote`, `expire_quote`, `trigger_webhook` (solo `sk_test_`) |
95
+ | `cord.webhooks` | `construct_event`, `construct_workflow_delivery`, `verify_signature`, `sign_payload` |
96
+
97
+ ```python
98
+ factura = cord.invoices.create(cliente_id=cliente_id, items=[...], currency="MXN")
99
+ # Un CFDI a un cliente extranjero sin mercancías: confírmalo al emitir.
100
+ cord.invoices.finalize(factura["id"], sin_comercio_exterior=True)
101
+
102
+ cord.workflows.invoke("wf_…", "invoice", [factura["id"]])
103
+
104
+ plan = cord.setup.propose(sitio="tunegocio.com", descripcion="Instalaciones eléctricas, cobro a 30 días")
105
+ print(plan["review_url"]) # una persona la aprueba ahí
106
+
107
+ cord.webhook_endpoints.update(endpoint_id, activo=False) # lo pausa
108
+ nuevo = cord.webhook_endpoints.rotate_secret(endpoint_id, 72)
109
+ print(nuevo["secret"], nuevo["secreto_anterior_expira"]) # el anterior sigue firmando 72 horas
110
+ ```
111
+
112
+ ## Webhooks
113
+
114
+ Verifica siempre sobre el cuerpo **crudo**, tal como llegó.
115
+
116
+ Flask:
117
+
118
+ ```python
119
+ import os
120
+ from flask import Flask, request
121
+ from cord import construct_event, WebhookSignatureError
122
+
123
+ app = Flask(__name__)
124
+
125
+ @app.post("/webhooks/cord")
126
+ def cord_webhook():
127
+ try:
128
+ event = construct_event(request.get_data(), request.headers, os.environ["CORD_WEBHOOK_SECRET"])
129
+ except WebhookSignatureError:
130
+ return "", 400
131
+ if event["event"] == "invoice.paid":
132
+ ...
133
+ return "ok"
134
+ ```
135
+
136
+ FastAPI:
137
+
138
+ ```python
139
+ import os
140
+ from fastapi import FastAPI, Request, Response
141
+ from cord import construct_event, WebhookSignatureError
142
+
143
+ app = FastAPI()
144
+
145
+ @app.post("/webhooks/cord")
146
+ async def cord_webhook(request: Request) -> Response:
147
+ try:
148
+ event = construct_event(await request.body(), request.headers, os.environ["CORD_WEBHOOK_SECRET"])
149
+ except WebhookSignatureError:
150
+ return Response(status_code=400)
151
+ if event["event"] == "invoice.paid":
152
+ ...
153
+ return Response("ok")
154
+ ```
155
+
156
+ En Django, el cuerpo crudo es `request.body` y la vista va con `@csrf_exempt`.
157
+
158
+ Usa el cuerpo crudo. Acepta `X-Cord-Signature-V1` o Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`), ambas con timestamp (5 minutos de tolerancia, `tolerance=`); con las dos basta con que cuadre una. La firma legacy solo con `allow_legacy_signature=True`. Deduplica por `event["id"]`.
159
+
160
+ `WebhookSignatureError.code`: `missing_secret`, `missing_signature`, `invalid_signature_header`, `timestamp_out_of_tolerance`, `signature_mismatch`, `legacy_signature_rejected` o `invalid_payload`.
161
+
162
+ ### El POST de un workflow
163
+
164
+ La acción "Mandar los datos a una URL" de Cord Workflows firma su POST igual, pero su cuerpo es `{ workflow, workflow_id, evento, objeto, objeto_id, enviado_en, mensaje?, datos }`:
165
+
166
+ ```python
167
+ from cord import construct_workflow_delivery
168
+
169
+ envio = construct_workflow_delivery(request.get_data(), request.headers, os.environ["CORD_WORKFLOW_SECRET"])
170
+ print(envio["evento"], envio["datos"])
171
+ ```
172
+
173
+ `verify_signature(payload, headers, secret)` solo comprueba la firma, sin leer el cuerpo.
174
+
175
+ ## Modo prueba
176
+
177
+ ```python
178
+ cord = Cord("sk_test_...")
179
+ cord.test_helpers.set_next_fiscal_outcome("pac_caido")
180
+ cord.test_helpers.trigger_webhook("invoice.paid")
181
+ cord.test_helpers.reset() # vacía el entorno de prueba; conserva llaves y endpoints
182
+ ```
@@ -0,0 +1,51 @@
1
+ [build-system]
2
+ requires = ["hatchling==1.32.4"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "cord-sdk"
7
+ dynamic = ["version"]
8
+ description = "SDK de Python para la API de Cord: cotizaciones, facturas, webhooks verificados, tipos y cliente async. Sin dependencias."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "Flouvia" }]
13
+ keywords = ["cord", "cotizaciones", "facturas", "webhooks", "api", "async"]
14
+ classifiers = [
15
+ "Development Status :: 5 - Production/Stable",
16
+ "Intended Audience :: Developers",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Programming Language :: Python :: 3.10",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Programming Language :: Python :: 3.14",
26
+ "Framework :: AsyncIO",
27
+ "Topic :: Office/Business :: Financial",
28
+ "Typing :: Typed",
29
+ ]
30
+
31
+ [project.optional-dependencies]
32
+ async = ["httpx>=0.27"]
33
+
34
+ [project.urls]
35
+ Homepage = "https://cordhq.app"
36
+ Documentation = "https://docs.cordhq.app/docs/desarrolladores/herramientas/sdks"
37
+ "API reference" = "https://docs.cordhq.app/docs/desarrolladores/referencia"
38
+
39
+ [tool.hatch.version]
40
+ path = "src/cord/_version.py"
41
+
42
+ [tool.hatch.build.targets.wheel]
43
+ packages = ["src/cord"]
44
+
45
+ [tool.hatch.build.targets.sdist]
46
+ include = ["src/cord", "README.md", "CHANGELOG.md"]
47
+
48
+ [tool.mypy]
49
+ strict = true
50
+ python_version = "3.10"
51
+ files = ["src"]
@@ -0,0 +1,25 @@
1
+ """SDK de Python para la API de Cord."""
2
+ from . import types
3
+ from ._http import API_VERSION, SDK_VERSION, AppInfo, CordError, CordResponse, RawResponse
4
+ from ._version import __version__
5
+ from .async_client import AsyncCord
6
+ from .client import Cord
7
+ from .webhooks import WebhookSignatureError, construct_event, construct_workflow_delivery, sign_payload, verify_signature
8
+
9
+ __all__ = [
10
+ "Cord",
11
+ "AsyncCord",
12
+ "AppInfo",
13
+ "CordError",
14
+ "CordResponse",
15
+ "RawResponse",
16
+ "WebhookSignatureError",
17
+ "construct_event",
18
+ "construct_workflow_delivery",
19
+ "verify_signature",
20
+ "sign_payload",
21
+ "types",
22
+ "API_VERSION",
23
+ "SDK_VERSION",
24
+ "__version__",
25
+ ]